@Jan: how is the output from Ghostdoc generated from the code itself?

Combine this with Resharper http://www.jetbrains.com which will inform you when comments for methods have parameters that don’t match or don’t exist or do exist and shouldn’t.

These tools can easily lead to development with zero comment stagnation. I agree with you for in code comments they should only be used on very hacky solutions and for nothing else. Everything else that SHOULD be commented needs to be refactored into variables with proper names for what it is, to seperate methods or even entirely new classes to avoid the need for having to read anything other than the code itself.

My assertion is that code without comments simply doesn’t work: http://gregbeech.com/blogs/tech/archive/2008/08/04/code-without-comments-is-code-that-doesn-t-work.aspx

For my team, verifying the validity of a comment in a changed section of code is part of the code review process. It really becomes second nature, and it is very easy to spot when the code has changed enough to be different from the comment provided. Beyond that, it is an indispensable reference tool for new developers to be able to hover over anything in the IDE and see the description, as opposed to jumping to definitions or running split windows.

Of course, it comes down to a little bit of personal preference and team buy-in, as well. The team, collectively, wants this level of functionality and understands the responsibility to make it valuable on an ongoing basis.

Beyond that, I am in complete agreement. When inline commenting becomes common practice, it is usually indicative of the need for refactoring. I try to limit my use of commenting to explicitly call out TODO items or to note why one approach was chosen over another.

1. Any logic that is somewhat complex should be put in its own method with a very descriptive name. In addition to making the code more testable, inline comments may be able to be avoided.

2. Anything within the body of a method that is not obvious given the purpose of the routine should have a comment.

3. Anything that relies on non-obvious business rules or unusual usage of an API should be commented.

Even though I enjoy reading other people’s code, English is still my primary language, and compiling code in my head to determine it’s intent becomes annoying very quickly.

I still don’t see the case for inline comments though. Like Keith mentioned, I’m more in favor of extracting a private method with a nice descriptive name than putting out a comment.

As I mentioned in my post: there are cases for inline comments, but I do find them rare as I mostly try to solve this with refactoring.

Take ASP.NET MVC. Great framework. ZERO comments(yet). If I wasn’t able to walk through the source code i’d never know what the expected outcome was supposed to be of many features. For example, a signature in the HtmlHelper class looks like this in the intellisense:

string Hidden(string name)

can anyone(who hasn’t already used the HtmlHelper, tell me what the does? clearly the name of the element will(should) be whatever value is in name, but what’s the id of the element going to be?

Here’s another one without a comment:

string TextBox(string name, object htmlAttributes)

What do you stick in htmlAttributes? Thankfully I consume enough caffeine and stay up late enough to read the source code and figure out what goes in there, but a simple little comment would have eliminated the need to read anything beyond the comment.

“The first name” as a comment is stupid, because it doesn’t give any useful information. However, comments like “Gets or Sets the First Name”, are important [to me] so i know, via intellisense, what’s readonly and what’s not before the compiler let’s me know.

I do agree, if the code speaks more than a comment could, leave the comment off. Superfluous comments that reiterate in psuedo code what the code does is always annoying. But if it’s a public API that someone else has to read, ask somebody else to look at it first for clarity before deciding the “no comment ever” direction.

Furthermore, could you imagine all of the .NET BCL without comments? Yikes. No thanks.