5 ms·

I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the r

I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just confuse people. How about putting that effort in writing the code line with clarity? The reader must read and understand it in any case. Stick with the code, people!

macintux 10y ago
I really don't get this attitude. Code cannot tell you what is not there, no matter how clearly you write it.
- kyberias 10y ago
  This is not black and white. Code comments have their place of course. For example, in sic. situations where one really needs to explain _why_ a certain approach was taken. But usually the why explanation is not needed. Also, code doesn't have to tell you _everything_. It doesn't have to tell you "what is not there". Maybe we can both learn here if you elaborated what you think code cannot tell, yet it should?
nercury 10y ago
No, the reader must not need to read the function to understand how it works. The idea would be that the function names are so good that one does not need to read the function contents, right? But some things are complicated and may not be expressible with the function name alone. That's why people write comments. To help readers understand the code. Let's say I am implementing some algorithm. I may mention the performance characteristics in the comment. Or I may let the readers dig into the code to find out what they are. Seriously, please don't follow "no comments" rule dogmatically.
- kyberias 10y ago
  No. If I have a function and I need to understand _how_it works_, that is, how does it implement some algorithm, of course I have to read every single line of code to understand how it works! If the function is named "quicksort", for example, and I suspect it has a bug, I really have to read it to understand whether it implements the quicksort algorithm correctly.
  - lisivka 10y ago
    Good luck with understanding of incorrect code of unknown algorithm.
  - sqeaky 10y ago
    I don't think starting a comment off with "No" is an effective tactic to convey your point or change someone else' mind. It seems clear to me, as an impartial third party, that there are merits and drawbacks to both of your school's of thought on comments. "No" attempts to shutdown the discussion and makes it hard to discuss these.
edblarney 10y ago
"The reader must read and understand it in any case." Because in the cases wherein the code is abstract or dense, a little 'English' can go a long way. Especially when making use of APIs that are weird and have weird behaviours. AKA: "I'm breaking xyz convention here because API abc has the following odd, undocumented behaviour (i.e. returns nulls when it should not)" Comments are not always good, but if there is any reasonable thoughtfulness to them, they will be 'mostly good'.

macintux 10y ago

I really don't get this attitude. Code cannot tell you what is not there, no matter how clearly you write it.

kyberias 10y ago
This is not black and white. Code comments have their place of course. For example, in sic. situations where one really needs to explain _why_ a certain approach was taken. But usually the why explanation is not needed. Also, code doesn't have to tell you _everything_. It doesn't have to tell you "what is not there". Maybe we can both learn here if you elaborated what you think code cannot tell, yet it should?

nercury 10y ago

No, the reader must not need to read the function to understand how it works. The idea would be that the function names are so good that one does not need to read the function contents, right? But some things are complicated and may not be expressible with the function name alone. That's why people write comments. To help readers understand the code. Let's say I am implementing some algorithm. I may mention the performance characteristics in the comment. Or I may let the readers dig into the code to find out what they are. Seriously, please don't follow "no comments" rule dogmatically.

kyberias 10y ago
No. If I have a function and I need to understand _how_it works_, that is, how does it implement some algorithm, of course I have to read every single line of code to understand how it works! If the function is named "quicksort", for example, and I suspect it has a bug, I really have to read it to understand whether it implements the quicksort algorithm correctly.
- lisivka 10y ago
  Good luck with understanding of incorrect code of unknown algorithm.
- sqeaky 10y ago
  I don't think starting a comment off with "No" is an effective tactic to convey your point or change someone else' mind. It seems clear to me, as an impartial third party, that there are merits and drawbacks to both of your school's of thought on comments. "No" attempts to shutdown the discussion and makes it hard to discuss these.

edblarney 10y ago

"The reader must read and understand it in any case." Because in the cases wherein the code is abstract or dense, a little 'English' can go a long way. Especially when making use of APIs that are weird and have weird behaviours. AKA: "I'm breaking xyz convention here because API abc has the following odd, undocumented behaviour (i.e. returns nulls when it should not)" Comments are not always good, but if there is any reasonable thoughtfulness to them, they will be 'mostly good'.