At the rails workshop yesterday, we got into a code readability discussion (one of programming "holy wars", i e endless debates). One thing that remains subjective is the use of comments. Since compiler optimizations give us great flexibility in how we code, I refactor intensely towards readability: Extracting helper methods, logic tests, etc - all in order to make the code almost as readable as normal english.

My take is that comments are almost a last resort, something you do when there is information that the reader needs, that the code cannot convey in a smooth manner. Essentially, I focus on making the code speak for itself, as much as I can.

Here are some articles that I liked, and a couple on c2 that are nice.

Comments are for communicating to other developers what the code does. The compiler eats simple text, yet other humans are often well served by images, and colors - hence we get color coding in our editors. Why hasn't this gotten further? I envision colorizing and straight out drawing beside the code, to augment it:

Drawing lines instead of making them with equal signs.

Custom color coding, where types can be assigned colors (I think layers) and use would show up easily as a background color, or the like.

Today, we create regions around code and insert a comment for them, why not pick a color as well? We will even more easily remember and browse the code.

Of course, I often create ad-hoc diagrams. Some I like to keep. These are for coders only - why not keep them with the code? Small diagrams, sitting right there in a comment. If word can do it, so can any modern editor, right?

Lutz Roeder (author of the .NET Reflector tool) had some thoughts in this direction, apparent from the presentations you can check on his page here.