this post was submitted on 06 Nov 2023
113 points (98.3% liked)
Programming
17408 readers
173 users here now
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities !webdev@programming.dev
founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
“I don’t need to comment this code, I wrote it so I know what it does”
And then
“Fuck, I should’ve commented this code, I have no idea what it does”
Comment. A lot.
Stage 2, "why does this code have nothing to do with the very detailed comments?"
Always comment the why, not the what/how. Bonus of doing this is you only need to update the comments when the why changes
git blameIf the comments don’t match the code then someone failed to properly review it.
Lol. That's why we comment with "why", rather than "what". The answer to "what the duck where we even thinking?" usually doesn't need updated until the commented code goes away.
Never understood this argument, it's the person's responsibility who changed the code to update the comments if needed. Otherwise they just implicitly admit that they did not read it or understand the context, or just plain did not care.
It just never works. Its important documentation breaks if changes are made. The best docs are baked into unittests