Ask HN: What's the most annoying part about writing code comments?
Working on a project and wondering what you guys think. Feel free to leave your opinion below.
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.
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.