Comment by Pxtl
2 months ago
> the code should explain itself.
This is a good goal. You should strive to make the code explain itself. To write code that does not need comments.
You will fail to reach that goal most of the time.
And when you fail to reach that goal, write the dang comments explaining why the code is the way that it is.
But you will also fail to keep the comments and code synchronized, and the comment will at some point no longer describe why the code is doing whatever it does
Which is why you're reviewing changes. I haven't memorized what every line of code does, if it was worth commenting then it was confusing-enough that it needed the comment and so I'll read the comment to make sense of the code being changed. If I don't read the comment that means the comment was too far from the confusing code.
Alternately, you can say the same about informative variable names or informative function names. "If I change the function then the name is no longer accurate". You don't say that because function names and variable names are short and clear and are close to the problem at hand. Do the same with comments.
Which is why the copilot hyper-verbosity is harmful. Comments need to be terse so your eyes don't filter them out as noise.
Yeah, my point has basically nothing to do with AI and is the argument against comment blocks in general. It's bad to store information in two places.
But copilot code review agent is pretty good at catching when code and comments diverge (even in unrelated documentation files).