[eliasson]

Antirez (redis creator) has written a good post [1] detailing his thoughts on code comments where he identifies nine type of comments used in Redis.

What surprised me was the use of "guide comments" which most people dismiss as too trivial. I agree with Antirez conclusion that they are valuable to help the reader acknowledge their understanding of the code.

[1] http://antirez.com/news/124

[godshatter]

I like guide comments because they show intent and because if you're scanning a function in an editor where comments stand out visually then it gives you a quick recipe of what the function nominally should be doing, which helps when you're trying to come up to speed in a code base.

They are even more useful if the author hates whitespace and tries to be too clever. I spend a lot of time trying to figure out code someone else wrote and appreciate anything that can set me in the right direction when trying to figure out what a particular function does.

[tacone]

The Laravel source code is an impressive example of that.