I think one of the most controversial and misunderstood aspects of writing code is effective code comments. It helps code review tremendously when good comments exist. The problem is how to write an effective comment. What you are trying to do and hopefully are going to do within the code snippet. this is wrapped up in the rhetoric of the comment. But comments are like song hooks. You have to be a coding genius to make a great comment.

Right off the bat, some will say it's a waste of time to make comments or at least massive comments. Okay, it looks like reason plays a part. Massive amount of comments are probably distractive and counter-productive. What I'm talking about is short clever comments that point you in the right direction and it starts when first writing code.

Most programs of any complexity have to be built up in stages. Posting "TODO comments" and pseudo code statements will go a long way in writing successful code in the shortest time. During the course of writing a program, refactoring or change in scope or approach come into play. The commenting needs to migrate gracefully as well.

The tricky part of commenting is how to make the comment effective. Making it short helps. Don't state the obvious. Point out what's salient about the code block, function, or class. Some variables are good to comment on where they are used since many will be used in several places. The guide would be: if it's obvious, don't comment. It there is a point that not obvious, make a comment. Even a reference to an external document made be important. At a later date, you or a reviewer may appreciate the aide.