Just read a nice blog post "The Top Ten Lies of Engineers". Below is one of the top ten lies that i would like to discuss:
"I'll comment the code, so that the next person can understand what I did."
This is a lie of good intentions. Really, the engineer did intend to comment the code but as the schedule slipped, priorities changed. The question put to management became: "Do you want me to comment the code or finish it sooner?" Guess what the answer was. Luckily, the lack of comments usually doesn't matter because the code is so crappy that a total rewrite is necessary in a year.
In order to finish the work before dateline, comment is one of the thing that I will sacrify. Since what I going to deliver is the system, not the comment. I am good in look for excuses.
However, I had found a way of comment my code and yet increase my productivity. This is not a magic or any brand new framework, just depend on a feature of your favourite IDE.
You may had guess it by now, the TODO tag. Some IDE (i.e. Eclipse which I used the most) have support the highlight of text such as TODO, FIXME within your code.
So before I start to dig deep into the code, I will write the skeleton of my program with all this TODO comment. Then I will start to code based on my TODO list. Once that steps is done, I will remove the word TODO, and it will be an ordinary comment now. (In fact, a comment with TODO make no different to compiler, it just make different to certain IDE.)
With this approach of comment, I am able to get a higher level view of the program I going to develop. It can be a good reminder for me about my progress. And when the program is delivered, it is already comment.