[freework]

Writing great comments is the kind of thing you really have to learn the hard way. When I first started coding, I used to comment my code in what I call the "micro-comment" format (comments that describe a single line of code). In my case, I had a project that I had to abandon for a period of few months. When I had to go back into that project to fix up some things, I couldn't anything, despite my micro-comments. I actually had to completely abandon a 20,000 line code base of a personal project because I couldn't read the code. That vivid experience of personally feeling the pain of my bad commenting is what taught me how to comment properly. I kept asking myself "Why the fuck did I do that? What is this code doing? Jeez, these comments are not helping me at all".

Now when I write things, I know to comment in what I call the "macro-comment". That is to say instead of writing a comment to describe a single line of code, you write comments to describe a block of code. Since that one project's fail, I haven't had that problem again.

Another point I want to make is that I really feel like my commenting skills are extremely valuable to me as a developer. I I had to have my brain erased, but I could choose one skill to remain, I'd choose keeping my code commenting skills. Its also the one skills that I care about the most in my co-workers. I don't care if you're really good at code golf. I don't care if you know haskell. Can you comment code properly? Whenever I interview for a job, I'm never able to demonstrate this skill. The Fizzbuzz problem doesn't allow me to show off my commenting skills. Writing a binary tree parser doesn't let me show off my documentation skills. I think it's the most important skill I have, but I never get the chance to show it off when interviewing.

[sophacles]

I almost fully agree with you, however there are also very important "micro comment" cases. IME this comes when implementing algorithms from papers. For example, when looking at some formula in a paper, and looking at a python implementation of it that uses numpy, there may not be an obvious 1:1 mapping. Numpy has some very powerful operations, so commenting each line with how that statement maps back to the algorithm makes revisiting or others' visits much easier to comprehend.

Another case is the "reminder note"... e.g. "This function also sets up the next step..." (I know, side effects and whatnot, but sometimes you're stuck with other people's libraries).

[mmatants]

So basically the generalized description is "don't document what is immediately evident from language syntax/function name itself".

[thebear]

Thank you for mentioning the case of implementing algorithms. I could not agree more. Without comments, it can be excruciatingly difficult for a reader to map (thanks for using that word, spot on!) the code to the high-level description of the algorithm. Comments provide that mapping. This gets more important as the algorithms become more complex, as in higher mathematics.

[ZoFreX]

> Whenever I interview for a job, I'm never able to demonstrate this skill. The Fizzbuzz problem doesn't allow me to show off my commenting skills.

A good interview process does let you show off your commenting skills. FizzBuzz is useless to measure ability, but wonderful for screening out those who have literally no ability. For my money one of the most valuable components to a good interview is a code sample, either look at code they've written in the past or give them a small problem to work through.

I might be biased though. I got more job offers from companies that interviewed me that way, including my current position :)