The Art of Code Comments | Hacker News Reader

The Art of Code Comments

css-tricks.com

15 pointskawera7 comments

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.

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 :-)

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.

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.

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

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.

Comments are really useful to explain reasoning behind complex sections, or edge cases that caused code to be written. Other than that I hate boilerplate comments, and try to make code self documenting.

Reply on news.ycombinator.com