4 ms·

Ask HN: What is your take on comments in a program?

I've been reading about the subject, and found out that people have a lot of varying opinions about this. Some say "clean code should have no comment", some use comments only when absolutely necessary, some day to document every function in details, and some day to use "why" comments, not "how" comments. What is your take on this?

ktpsns 7y ago
What I don't like is code where comments explain obvious things. Code should be speaking for itself. This is an easy demand for pure administrative code ("high level" or how you want to call it) in an expressive language. Once it comes to the heart of the matter, such as a challenging algorithm which is hard to follow, I like extensive comments about the meaning of variables, etc. Interestingly, people comment trivial stuff but don't comment the complex ones. That's a natural phenomena called Parkinson's law of triviality.
alpaca128 7y ago
I mainly comment in two situations: When I wrote some weird code due to non-obvious reasons and want to clear up the reasoning; this makes later considerations easier. Or when I had difficulties understanding the meaning of a snippet and want to make it easier to read and understand in the future. I get why many people say comments are bad, but that doesn't mean you should never use them. And the "why" comments are definitely the most helpful ones in my opinion, I agree; one can easily look at the expressions and function calls and understand what's happening, but sometimes I want to know why the code adds 1 to some index, and a single short comment can clear that up. And if the reasoning was incorrect then that comment also tells you what to throw away.
kgraves 7y ago
As a manager who frequents HN a lot, I really don't understand this 'why' and 'how' in comments and programmer reluctance to use them, all I see is just code comments, like notes. Could one explain or provide examples these in a way I can understand?
- alpaca128 7y ago
  This is how I understand it: how: "reset values in the array with a loop" why: "reset values so they don't affect the behaviour of foo()" The first explains what happens in the code and how, which is not as important because it should be already obvious from the code itself. While the second one explains the reason this part of the code exists, why it's important, why it was written that way.
  - mytailorisrich 7y ago
    What the code does is not always obvious without quite detailed analysis. In those cases a comment does help. In general, if I have to put some effort into a piece of code and I understand now only because I put that effort in then my future self won't immediately understand it in 6 months time (and right now I'm the only person to understand it immediately). In these cases, 'how' comments help. Commenting is mostly common sense, imho.
- seren 7y ago
  "how" or "what" is a purely describing what is happening. // Initialization of foo initFoo(); // Send first Bar Message SendFirstBarMsg(); Descriptive comments have usually low value because it can be (re)deduced by reading the code. But I rather read a code with too much comments that none. On the other hand, the "why" is explaining the reasoning why it is done that way. And usually it can have been the result of bug fix, long investigation, or architectural choice so this is precious (and costly) knowledge. initFoo(); // first Bar Message should be sent after foo init, otherwise it can create a rare race condition when bar message is received before foo is ready. SendFirstBarMsg(); In the second example, the information about race condition is not immediately available just by reading that part of the code. This is also a (rather light) safeguard that if someone refactor the code at some point, it won't recreate a bug that had already been found. My example is a bit contrived, but this is the idea, and that is why for me, the "why" is really important, because this is your team knowledge and experience you are distilling inside the code. Most developers are reluctant to use the first kind of descriptive comments because, at a point, it adds more clutter, this is mostly redundant information. If you have meaningful variables and method names, this kind of comment should be superfluous. Another rule of thumb is that code is usually written once, and will be read 10, 100 or 1000 times by other people (depending on the context or the longevity of the code base), so in my opinion, code and comments should be optimized for the long term, and for easy comprehension, because this is where most time time will be spent on the code. To address op point "clean code should have no comment", even if you have the cleanest code base ever, you have not guarantee that down the line the people that are going to maintain it in 5 years, will be as proficient as the original writer. And additionally, these people won't have access to why it was written that way, (maybe after trying something else that did not work) so it is really important to provide them with some clues.
krapp 7y ago
Speaking only from personal experience on personal projects, I have screwed myself up far more often by not writing comments, or deleting comments prematurely in order to "clean up" the codebase, than I have by writing too many comments. I disagree that code should never have comments. There's no such thing as perfectly self-documenting code of more than trivial complexity, the intended means of documentation for code is comments. That's what they're there for, they're a tool, use them. Beyond that, it's entirely a matter of style and personal preference.
mytailorisrich 7y ago
Common sense approach: add comments where it helps to understand the code. Commenting that i++ increments the index adds nothing. Commenting that sleep(n) is there because there must be a delay between a and b because x and y is useful.

ktpsns 7y ago

What I don't like is code where comments explain obvious things. Code should be speaking for itself. This is an easy demand for pure administrative code ("high level" or how you want to call it) in an expressive language. Once it comes to the heart of the matter, such as a challenging algorithm which is hard to follow, I like extensive comments about the meaning of variables, etc. Interestingly, people comment trivial stuff but don't comment the complex ones. That's a natural phenomena called Parkinson's law of triviality.

alpaca128 7y ago

I mainly comment in two situations: When I wrote some weird code due to non-obvious reasons and want to clear up the reasoning; this makes later considerations easier. Or when I had difficulties understanding the meaning of a snippet and want to make it easier to read and understand in the future. I get why many people say comments are bad, but that doesn't mean you should never use them. And the "why" comments are definitely the most helpful ones in my opinion, I agree; one can easily look at the expressions and function calls and understand what's happening, but sometimes I want to know why the code adds 1 to some index, and a single short comment can clear that up. And if the reasoning was incorrect then that comment also tells you what to throw away.

kgraves 7y ago

As a manager who frequents HN a lot, I really don't understand this 'why' and 'how' in comments and programmer reluctance to use them, all I see is just code comments, like notes. Could one explain or provide examples these in a way I can understand?

alpaca128 7y ago
This is how I understand it: how: "reset values in the array with a loop" why: "reset values so they don't affect the behaviour of foo()" The first explains what happens in the code and how, which is not as important because it should be already obvious from the code itself. While the second one explains the reason this part of the code exists, why it's important, why it was written that way.
- mytailorisrich 7y ago
  What the code does is not always obvious without quite detailed analysis. In those cases a comment does help. In general, if I have to put some effort into a piece of code and I understand now only because I put that effort in then my future self won't immediately understand it in 6 months time (and right now I'm the only person to understand it immediately). In these cases, 'how' comments help. Commenting is mostly common sense, imho.
seren 7y ago
"how" or "what" is a purely describing what is happening. // Initialization of foo initFoo(); // Send first Bar Message SendFirstBarMsg(); Descriptive comments have usually low value because it can be (re)deduced by reading the code. But I rather read a code with too much comments that none. On the other hand, the "why" is explaining the reasoning why it is done that way. And usually it can have been the result of bug fix, long investigation, or architectural choice so this is precious (and costly) knowledge. initFoo(); // first Bar Message should be sent after foo init, otherwise it can create a rare race condition when bar message is received before foo is ready. SendFirstBarMsg(); In the second example, the information about race condition is not immediately available just by reading that part of the code. This is also a (rather light) safeguard that if someone refactor the code at some point, it won't recreate a bug that had already been found. My example is a bit contrived, but this is the idea, and that is why for me, the "why" is really important, because this is your team knowledge and experience you are distilling inside the code. Most developers are reluctant to use the first kind of descriptive comments because, at a point, it adds more clutter, this is mostly redundant information. If you have meaningful variables and method names, this kind of comment should be superfluous. Another rule of thumb is that code is usually written once, and will be read 10, 100 or 1000 times by other people (depending on the context or the longevity of the code base), so in my opinion, code and comments should be optimized for the long term, and for easy comprehension, because this is where most time time will be spent on the code. To address op point "clean code should have no comment", even if you have the cleanest code base ever, you have not guarantee that down the line the people that are going to maintain it in 5 years, will be as proficient as the original writer. And additionally, these people won't have access to why it was written that way, (maybe after trying something else that did not work) so it is really important to provide them with some clues.

krapp 7y ago

Speaking only from personal experience on personal projects, I have screwed myself up far more often by not writing comments, or deleting comments prematurely in order to "clean up" the codebase, than I have by writing too many comments. I disagree that code should never have comments. There's no such thing as perfectly self-documenting code of more than trivial complexity, the intended means of documentation for code is comments. That's what they're there for, they're a tool, use them. Beyond that, it's entirely a matter of style and personal preference.

mytailorisrich 7y ago

Common sense approach: add comments where it helps to understand the code. Commenting that i++ increments the index adds nothing. Commenting that sleep(n) is there because there must be a delay between a and b because x and y is useful.