This came across my Hacker News feed the other day, “I’ve never seen a language’s style guide recommend avoiding comments before.” After reading the link it became clear that the HN title was link bait. What the Haskel documentation was stating is something any good programmer already knows. Don’t document every line of code.
x = x + 1; // Increment x by 1
This comment is not required as it is obvious what it is doing. My rule of thumb for commenting is; if it’s complicated or was problematic, it requires a comment explaining the why or why not. A good programmer should be able to read through the simple code and know what is going on. However, commenting on why you wrote something the way you did would help yourself or the next guy to know what you were thinking.
This comes to light not only when I am looking at code I wrote 5 years ago, but recently I had a co-worker leave. He didn’t write many (read any) comments in his code. Now in some cases I am running debug just to see what the application is doing before I can think of fixing that bug or making that change.
So do your future self or co-worker a favor and comment… but not too much.
No responses yet