
The Art of Code Comments - kawera
https://css-tricks.com/the-art-of-comments/
======
rdiddly
Comments are one of the secrets to maintainable code. Your code will
inevitably fall short of the ideal of completely explaining itself, so not
adding comments is basically racking up tech debt.

~~~
progman
That's true for most languages. However, some languages are so well designed
for maintainability that they barely need verbose comments. Ada is such a
language. I have no problems to understand my own Ada code written 10 years
ago. However, I had difficulties to understand my own Haskell code just one
week later :-)

------
Jeff_Brown
Three totally different points:

Sometimes I find it useful to add a comment of the form "this function is
called by that function" to the called function.

An editor that let you mark comments as explaining how, explaining why,
identifying further work that needs doing, etc. and then filter out the
irrelevant ones would be nice.

It ought to be that we could attach a comment to a specific expression, rather
than just sticking it nearby.

------
frigo_1337
One thing from Clean Code that fundamentally changed the way I write code was
the bit about how “Comments Lie”.

I hadn’t really thought about it much before. But since then, I see lying
comments absolutely everywhere. Many of which I have written myself. The
author is right, comments are really hard to maintain.

Nowadays I try my absolute hardest to avoid writing comments. 9 out of 10
times, it can be solved with some refactoring.

~~~
inertiatic
Thinking code can be "self-documenting" is one of the biggest delusions of
this field.

~~~
abritinthebay
You’re being downvoted but it’s extremely true.

Code should strive to be as self-documenting _as possible_ but there will
always need to be some level of documentation- and good comments are _part_ of
that.

One other part of that effort should be good unit, integration, and
acceptance, tests.

