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.
I hear this quite a bit, and think there’s actually a good deal of nuance to it. I’ve seen places that insisted on comments for everything, and it was silly, a significant number of comments had no value. This made people not read comments, as opposed to other places I’ve worked with very few comments - when you ran across a comment you gave it more weight (something here was complex, or not as simple as it seemed).
So imo, use comments which can communicate effectively, but use them sparingly for important parts that are complicated, for the rest attempt to communicate with the code itself.
step 1: learn to comment everything. This will helps code reviewer to catch errors because your code doesn’t match the comments
step 2: write your code in a way that makes comments useless and stop writting them
step 3: write your code just like you did in step 2, but documents all the things that you didn’t do, or why the code is more complicated than the naive approach. If your arguments are weak you are not in step 3, but in step 1.
I find that writing detailed comments about things that aren’t clear in the code often lead me to a better, more clear solution. Same thing with writing detailed commit messages. So many times I realize something better during the message, I’ll finish the commit and then almost immediately amend that commit with the better way.
“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
I hear this quite a bit, and think there’s actually a good deal of nuance to it. I’ve seen places that insisted on comments for everything, and it was silly, a significant number of comments had no value. This made people not read comments, as opposed to other places I’ve worked with very few comments - when you ran across a comment you gave it more weight (something here was complex, or not as simple as it seemed).
So imo, use comments which can communicate effectively, but use them sparingly for important parts that are complicated, for the rest attempt to communicate with the code itself.
step 1: learn to comment everything. This will helps code reviewer to catch errors because your code doesn’t match the comments
step 2: write your code in a way that makes comments useless and stop writting them
step 3: write your code just like you did in step 2, but documents all the things that you didn’t do, or why the code is more complicated than the naive approach. If your arguments are weak you are not in step 3, but in step 1.
I find that writing detailed comments about things that aren’t clear in the code often lead me to a better, more clear solution. Same thing with writing detailed commit messages. So many times I realize something better during the message, I’ll finish the commit and then almost immediately amend that commit with the better way.
Yep, was going to say that refactoring my own code taught me a lot