Ask HN: What's the most annoying part about writing code comments?

https://news.ycombinator.com/item?id=30656276

by Nevin1901 • 4 years ago

3 3 4 years ago

news.ycombinator.com

Working on a project and wondering what you guys think. Feel free to leave your opinion below.

davismwfl• 4 years ago

The most annoying part is the people who don't write comments.

Code comments are important (sometimes more important than the code), even for code that seems self describing, as in many cases putting a few notes of the "why" is super critical to prevent people from making breaking changes later. That said, I am not advocating for commenting completely self describing code lines, e.g. // for loop etc.

My personal work style is I first write comments as the outline of what I want to have happen then fill in the details via code. At the end, I'll remove the unnecessary comments, but by doing this it helps me make sure my code is fully commented and helps me organize my thoughts before just writing code. The worst case is I sometimes leave unnecessary comments but that's fairly minor IMO. This method works at any level of code too, e.g. modules, interfaces, files, functions etc

Frankly commenting this way has saved me countless hours of debugging, especially in more complex and code dense functions, algorithms is a good example. Non trivial lambdas is another good example where a good comment can save a ton of time.

I also require function header comments with parameter descriptions and return value details etc. Tools like doxygen are invaluable when you work with teams that need to share details on interfaces etc.

GianFabien• 4 years ago

Totally agree.

Source code is for the compiler to read and comments for the humans to read so that they understand the constraints, reasons, etc that things were done they were. In my younger days, I tended to write "self-documenting code" which basically didn't. I lost count of the number of times code written a few months prior made no sense to me and I had to painstakingly re-read and understand the source code. That's how I learned to use comments as the breadcrumbs to follow months / years down the track.

If you write throwaway code, then no need to bother with the comments. Make sure you do throw away such code.

WheelsAtLarge• 4 years ago

keeping them up to date. A never ending battle that can't be won.

Ask HN: What's the most annoying part about writing code comments?

Related Stories