Brian Marick, in a related blog entry, discusses an interesting perspective on the issue of comments in source code. As he frequently does, Brian brings another dimension and perspective to the topic. Brian discusses the expectations of your audience and provides an example of code in C, that if directly translated to Lisp, is not too easy to understand. The "mis"understanding exists because of the generqally accepted style for Lisp code, which is different from C code.

This caused me to think of another example. Lately, I work with C#, but still work with Java from time to time. Java has anonymous inner classes, C# does not. In many cases, anonymous inner classes improves the clarity and simplicity of the code. Given the similarities between C# and Java, I tend to read Java code with my C# hat on, which always causes me to pause when I read code that uses anonymous inner classes.

Should this code have comments, explaining the intention and use of the anonymous inner class? From one reader's point of view, the code may be clean and not need comments, but another reader, as in my example, might benefit from them.

However, I think it is a death spiral if you attempt to accomodate too many perspectives. Do you comment Java for C# readers? What about Java for Ruby, Lisp, Prolog, Python....readers?

Let's assume you only consider the experienced Java reader. On the refactoring group, I see many different opinions regarding the best style and constructs for any particular code snippet.

I don't think this justifies source code comments. Comments assume that the language (English for example) and the prose is readable by all, or at least more than the code. (There is also the issue of keeping the comments in synch with the code as it changes, which is one of my primary practical reasons against comments.)

These considerations cause me to realize something: both the definition of clean code and explanatory comments make assumptions about the reader, her context and her experience. This is true about any writing, but it is particularly complicated for the software developer. The expected future reader can vary dramatically but will probably be faced with some practical reason to quickly understand and use (modify or integrate) the source code and accompanying comments.

This leaves me with more questions than any conclusions. Though I still think a developer should challenge himself to improve his code before he writes a comment, I wonder for whom should the code be made more readable?