3 ms·

Sure! The beginnings of functions, for instance, are great places to comment, perhaps even including a definition of some of the subroutines within it. In the

Sure! The beginnings of functions, for instance, are great places to comment, perhaps even including a definition of some of the subroutines within it. In the case of an exceptionally large subroutine, commenting within the subroutine may be advantageous - but at that point you may consider another function to replace that larger chunk. Variable names that are perhaps obscure and are not practical to rename for whatever reason can also use comments. Class headers are of course also a great place to comment, to explain the purpose of the class. Good comments can lead to better code. :)

tchaffee 7y ago
You didn't really answer my question though. I didn't ask where you should comment. I asked for an objective definition of what over-commenting would be.
- evil-olive 7y ago
  > I asked for an objective definition of what over-commenting would be. I don't think what you're asking for is possible. It's an inherently subjective standard. If an objective definition were possible, then it'd be possible to write a static analysis tool that reads both your code and the comments and flags "over-commenting on line 23, under-commenting on line 457". That could be done with sufficiently advanced AI, but at that point it would just be the subjective opinion of the tool's author being enforced.
- replyguy912 7y ago
  over-commenting is explaining in pseudo-english what you've written in code. Prentend you are at the United Nations but you speak all the langauges, so you don't need a word-for-word translation. You don't understand to motivations of every speaker though, nor their cultural influences and a million other factors, so context is super important. In the briefings you get some of the information is not new; but if the vast majority of what you're told is obvious or discernable from what people say, you're looking at over commenting. It's not a yes-no thing but a balance of evidence, subjective opinion.

tchaffee 7y ago

You didn't really answer my question though. I didn't ask where you should comment. I asked for an objective definition of what over-commenting would be.

evil-olive 7y ago
> I asked for an objective definition of what over-commenting would be. I don't think what you're asking for is possible. It's an inherently subjective standard. If an objective definition were possible, then it'd be possible to write a static analysis tool that reads both your code and the comments and flags "over-commenting on line 23, under-commenting on line 457". That could be done with sufficiently advanced AI, but at that point it would just be the subjective opinion of the tool's author being enforced.
replyguy912 7y ago
over-commenting is explaining in pseudo-english what you've written in code. Prentend you are at the United Nations but you speak all the langauges, so you don't need a word-for-word translation. You don't understand to motivations of every speaker though, nor their cultural influences and a million other factors, so context is super important. In the briefings you get some of the information is not new; but if the vast majority of what you're told is obvious or discernable from what people say, you're looking at over commenting. It's not a yes-no thing but a balance of evidence, subjective opinion.