I can't believe the stupidity of putting XML tags in comments. Yes, structured comments are good, but why on Earth would you saddle coders with the verbosity and noise of actual XML tags? Javadoc did a good job compromising between structure and natural formatting.

The best thing would be for the IDE team to make it so you just typed in the comment how it should look with formatting, etc.. Lutz Roeder used to have a tool that did that, but it seems he's taken it down from his site.

Second, amen to your 4 guidelines! If you are going to thoroughly document your code with code samples and descriptions like MSDN doc (using NDoc), then put all the extensive stuff in a referenced file so that only the critical part is seen in the code window. I don't know how to make sure the external XML files stay in sync with the code, but there should be a tool for that too!

I wish Roland Weigelt's GhostDoc worked for VB too. Bummer (http://www.roland-weigelt.de/ghostdoc/).

Hmm, I thought JavaDoc used XML tags too, but I guess it doesn't:

http://java.sun.com/j2se/javadoc/writingdoccomments/

I have to agree with Ned. After looking at some JavaDoc samples, I do think JavaDoc would be easier to maintain.

I agree in large part with the idea of not going overboard with commenting. I personally think rule #4 is the most important. So-called self-commenting code is probably the best. My own commenting rules are:
1. Write self-commenting code (meaning, it doesn't need commenting because it is self explanatory. (unlike this explanation itself, though, apparently).
2. Comments answers the question "Why", and not "How" or "What" (i.e. Why are you doing something the way you do it. If you need to explain How or What the code is doing, you have a problem). This basically is the same rule as #1. The question of Why often cannot be derived from the code (the rationale or thought process behind writing code in a certain way, etc.)

We separate entirely application development from UI develpment. Our UI coders need good assembly documentation, and explaining the intents of a method or the meaning of a property is needed in the summary section. The Why you want to put will go into a remarks section if needed. All these might be a pain. But they are needed, and they do help assembly developers to review back their doc and do corrections too.

Fine, but put *brief* comments as close as possible to the code they're referring to. Don't stuff 2kb of text at the top of the function and expect anyone to A) look at it or B) maintain it. That's my main beef here.

This is hilarious:

http://www.cenqua.com/commentator/
---
The Commentator uses revolutionary real-time language processing to actually grok your code and add the necessary comments on the fly. No more doco to slow you down. Just install The Commentator and watch as your coding elegance is eloquently decorated with insightful, nuanced commentary ...as you type. What's more, The Commentator's powerful Personality Controls allow you to tweak it's output so completely that it's as if The Commentator is speaking for you. In your voice. Explaining to those that need it, so that you can get on and get busy.

When you fully document your API, you get a big advantage over most uncommented/partially commented code: each piece of your API, like a method, becomes well-defined, meaning for each input, you can predict the output. You can then fully change the implementation without introducing any bugs as long as it conforms to the API. Self-documenting code has the same advantage but you have to make sure that you take all corner cases into account, such as which things can be null and what a null return value means.

Additionally, if you program with interfaces, it is very useful to fully document their methods because there is no code that can document itself.

That said, who the hell would want to maintain XML that would probably be as large as the code? That's like 2 code bases. Ridiculous.

loved the http://www.cenqua.com/commentator/ reference!

I'm afraid I score a verbosity=10 though - sorry see below

(example code)
//********************************************************************
//** Author : Steve Parker
//**
//** Method : Network (Constructor)
//**
//** Date : 20th Nov 03
//**
//** Description: The network object performs four main tasks,
//** 1. Retrieval of NT Groups
//** 2. Retrieval of the User Name currently logged in
//** 3. Find the name of the PDC
//** 4. Connect a network drive to a folder path
//**
//** Because the application should work for both WinX
//** and NT type platforms (i.e. 95,98 and 2000, XP)
//** This application does not bind at compile time to
//** the required libraries as it would mean the resulting
//** executable would not work on every platfrom. Instead
//** the required libraries are referenced by the LoadLibrary
//** command.
//** Note : It is worth noting that the 32 bit type operations
//** used from NETAPI32 use Wide characters and the 16 bit
//** versions do not. Because of this, the code is almost
//** replicated for each type - I am convinced that there is
//** a more efficient way of writing the code for this part
//** (especially the EnumerateNTGroups method) but am unsure
//** of how to do this.
//**
//** Parameters : (overloaded)
//**
//** logger CLogger - This is the created Logger object that
//** allows the Network class to log actions as they are
//** performed. Each log entry has a specific log level (the
//** default is GENERAL). see Logger.cpp for more information
//** on this class.
//**
//**
//********************************************************************
CNetwork::CNetwork(CLogger* logger)
{
m_log = logger;
this->SetDLLPath(); //** read in the DLL path from the config XML document, and assign it to this->DLLPath.
}

You're missing the main benefit of these verbose comments - generating an easy-to-read help file on how to use your component (class, whatever). Plus the documentation on each parameter is nice for intellisense - the XML structures it so that VS knows which description goes with which parameter. Plus you don't have to remember the exact structure - if you type /// at the beginning of a method VS will generate the stub of the comments for you, including stubs for each parameter. But your main point is still valid - reading all that XML gobbledygood while actually inside class with the comments is not that easy.

see:

http://www.developer.com/xml/article.php/3377051
http://ndoc.sourceforge.net

I had trouble finding this information on the Internet!
Thank you for taking the time to post!

wow...so much whining about this. At least there is some standard way to document VB code now. If you don't like it, don't use it, or use only part of it, or write a tool that makes editing these elements easier, then market it and buy a boat in Ft. Lauderdale.

The fact is, code needs to be documented, a means of conveying description and method signatures. Anyone who doesn't think so is a hack, or not a real developer, or an arrogant ass who doesn't play well with others.

I could not agree more with what Wen Lai said :

<< Comments answer the question "Why", and not "How" or "What" >>

This should be the golden rule of code commenting.

In the real world things has to happen. So, comments has to be written and updated. Moreover, time is valuable so documenting every thing even you do not add any new information (like writing comments about every getter method - "getEmailAddres", "getDeliveryDate"... - in a value object) is a nonsense. I think it's better to avoid any stupid formal application of a rule. We are programmers, not robots!

By my opinion XML is better for code, not for humans. Sometimes programmers has to write some XML code. But when they ends up to write a lot of XML code (i remember the times before the EJB3 era) their programming experience tends to become worse.

A good IDE will auto-generate the structure of those verbose comments and fold them up when you're done. That way the signal to noise ratio is kept sane and you're given the potential of pretty API docs later.