I didn't have time to read the entire thing. I scanned it quickly and have to say that I don't think I disagree with the recommendations of that paper. In gen

I didn't have time to read the entire thing. I scanned it quickly and have to say that I don't think I disagree with the recommendations of that paper. In general terms comments should not describe the mechanics of the code "looping through all available names" but rather the intent "Find the user name". That comments get out of sync with code is a fact. That they stay out of sync is inexcusable. What I will generally do is to fully test and debug a chunk of code and then go back and annotate. I sometimes have a "Go comment the code" item in my to-do list and will spend time here and there cleaning-up and clarifying comments. The other interesting thing that can happen when commenting this way is that you can find issues with the code or identify refactoring opportunities. It's like sitting down to explain what the code is doing to another capable programmer as opposes to a 12 year old who is just starting to learn how to program. Maybe that's the best way to put it. What do you say to an experience programmer if you had to do a code review and explain your code? That should go in the comments. If a method or subroutine is absolutely trivial then you say "This finds the average of the voltages across these four inputs". If, on the other hand, the routine is more complex, you have to describe the overall intent "this calculates the values of the missing pixels" and then dive within the module to explain some of the specific techniques being used "Polyphase FIR filter to interpolate image data for missing color samples" or "Bounds-limited adder to clip FIR filter data to legal image data range". In other words, you don't explain every line of code but rather functional chunks that make it easier to navigate it and understand what is being done at a macro level and why. Again, my peeve is with projects that have files upon files with not a single comment. I don't expect a book.