[cyanoacry]

This approach works well in only one situation: when your code isn't doing anything substantial in terms of data processing.

For me, comments are best used at explaining _why this is happening_, not what is happening.

By far one of the best examples of code commenting I've seen is the explanation of the L2ARC (the level 2 adaptive cache) in ZFS: http://fxr.watson.org/fxr/source/cddl/contrib/opensolaris/ut... . Most of the ZFS codebase is extremely well documented due to its comments, and it helps a lot having the documentation _in the code_, to provide context (something that commit logs, by default, don't).

[davidgerard]

The hard part IME is keeping your audience in mind.

Your future self? Your coworker who might be hired next month? Your past self who would have wished to read said comment?

Who is the audience for the comment?