There is a way. See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfinclude.asp

I prefer to keep the comments inline with code, however—less chance of the two getting out of sync.

It is a rare occasion when I can’t understand and appreciate your point of view, but I’m afraid I must respectfully disagree with you on this topic. I don’t believe your arguments are strong enough to support the elimination of code comments.

Your first point appears to say, “Most people don’t know how to write effective code comments (or they refuse to write effective code comments), and therefore the practice of commenting code is invalid.” If I applied this philosophy unilaterally based on the development teams I’ve worked with, I would have to throw out comments, object oriented development, exceptions, threads, XSLT, and a myriad of other practices and tools.

Your second point focuses on the possibility that the comments will get out of synch with the source code and degenerate such that they become more burden than boon. Again, let’s test this criterion by applying it to a coding practice that I believe you will agree has known benefits.

Test units created for Test Driven Development most often reside in a separate file from the source code. Because of this, the likelihood of a test unit getting out of synch with the production code it represents is far greater than that of an inline comment getting out of synch. Like comments, test units may also threaten a project if they are poorly implemented or maintained. If they are too general, they may instill a false sense of security when code is changed; if they are wrong, they could cause more issues than they help fix. Couldn’t I logically conclude, “Wrong tests are usually much worse than no tests at all?”

Obviously, you wouldn’t think of discarding object oriented development or TDD because most people don’t know how to do it well – you would work to educate your team.

A poorly implemented method written in the C# language doesn’t indicate that the C# language is worthless. Likewise, the fact that bad comments exist does not disqualify commenting as a useful practice. Comments are part of the code – the presence of bad comments represents a failure by developers to properly implement and/or maintain their code.

The real question is simply, “Do comments provide sufficient benefit to justify the time required to write and maintain them?” I believe they do.

Consider the following Java language example:

public static void populateListFromDelimitedText(List target, String delimitedText, String delimiter) {
if (target != null) {
SimpleStringTokenizer tokenizer = new SimpleStringTokenizer(delimitedText, delimiter);
while (tokenizer.hasMoreTokens()) {
target.add(tokenizer.nextToken());
}
}
}

Obviously, this method tokenizes a delimited String and stores the tokens in the provided list. The method is simple, singular of purpose, and uses descriptive names. That’s all you need. Right?

Lets look a little closer. What will happen if the delimitedString parameter is null or blank? What if the delimiter parameter is null or blank? What if the delimiter parameter is more than one character – will each character be used as a delimiter or will they be used collectively? You’ll have to dig through the SimpleStringTokenizer class to know for sure – so much for abstraction and information hiding.

Now imagine you’re refactoring this method. Is it obvious to you I’m using a custom string tokenizer because java.util.StringTokenizer discards empty tokens? Or would you simply assume I didn’t know what I was doing and change my implementation?

Granted, you might ferret out these details with a good test unit. But is that practical? A test unit isn’t likely to reveal the business need for a method (the why); it will expose only the details of the method behavior (the how). Furthermore, a test unit is still code. No matter how well written it is, it is still designed primarily for consumption by a machine; code will never be as clear as a comment written in the native language of the developer. Don’t get me wrong – I’m not saying code comments can replace TDD. However, TDD is no replacement for code comments either.

Lastly, I find your support of documentation for public APIs puzzling in light of your aversion to code comments. Assemblies, classes, and methods are all levels of abstraction. If one level warrants documentation, shouldn ’t they all? Likewise, if meaningful variable, method, and class names are sufficient for one level, shouldn’t they be good enough for every level?

I’m not interested in holding on to pet practices if they don’t add value, but I think you’re underestimating the value of well-made, well-maintained comments. I find comments invaluable when I am responsible for maintaining code. I have asked those to whom I have handed off projects if they found my comments useful – the answer has always been yes. And while I have been asked to include more detail in my comments, I have never been asked to reduce or eliminate the comments in my code.

I’d be curious to know if any supporters of self-documenting code have asked those maintaining their code what they would like to see in the way of comments. Have you actually had a developer responsible for maintaining your code tell you that he wanted to see few, if any comments in the code you create?

David,

I was merely trying to state the fact that the majority of comments state the blatantly obvious. Anyone reading my source code could probably figure out that i = i + 1 means increment i by 1. There is no need for a comment to disclose this fact. A comment may be necessary to tell me *why* i is being incremented.

Again, I’m not against comments at all… I’m against comments that tell me what is happening, as this is a sign that the code could be clearer. I’m all for comments that tell me why something is happening.

I think that you are right Matt. // (IMHO)

I would rather have code that has well named methods and members. // <- profound statement

I also don’t like code that uses single letter members, such as: x = x + 1 // what the heck is x?

:)