
Ask HN: What is your take on comments in a program? - MarcellusDrum
I&#x27;ve been reading about the subject, and found out that people have a lot of varying opinions about this. Some say &quot;clean code should have no comment&quot;, some use comments only when absolutely necessary, some day to document every function in details, and some day to use &quot;why&quot; comments, not &quot;how&quot; comments.<p>What is your take on this?
======
ktpsns
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
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.

------
krapp
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.

------
kgraves
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
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
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.

------
mytailorisrich
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.

