''' ***********************************************************
  ''' Copyright [year]  [client name]. All rights reserved.
  ''' ***********************************************************
  ''' Class.Method:     IConfigProvider.GetSetting
  ''' <summary>
  '''  [summary goes here] 
  ''' </summary>
  ''' <param name="name">
  '''       [description goes here]. 
  '''       Value Type: <see cref="String" />   (System.String)
  ''' </param>
  ''' <param name="defaultValue">
  '''       [description goes here]. 
  '''       Value Type: <see cref="String" />   (System.String)
  ''' </param>
  ''' <exception cref="System.ApplicationException">
  '''       Thrown when... 
  ''' </exception>
  ''' <returns><see cref="String" />(System.String)</returns>
  ''' <remarks><para><pre>
  ''' RevisionHistory: 
  ''' -----------------------------------------------------------
  ''' Date        Name              Description
  ''' -----------------------------------------------------------
  ''' mm/dd/yyyy  [logged in user]  Initial Creation
  ''' </pre></para>
  ''' </remarks>
  ''' -----------------------------------------------------------    

I 3 Steve McConnell*
Coding Horror
programming and human factors
by Jeff Atwood
Enter your search terms Submit search form
Web Coding Horror

November 13, 2004
When Good Comments Go Bad

Now that XML comments are confirmed for VB.NET in VS.NET 2005, I've started to aggressively adopt the VBCommenter add-in, which adds XML comment support to the current version of VS.NET.

XML comments are great primarily because of the additional IDE tooltip feedback they provide to developers for methods and variables-- well, as long as you're using C#. If you're using VB.NET you have to reference a binary version of the project to get that to work, at least until VS.Next.

However, as a general purpose documentation tool, XML comments are.. kind of verbose, hard to maintain, and annoying. The potential for abuse is high. This 15 seconds article is a prime example; just take a look at the author's recommended XML documentation template:

''' ***********************************************************
''' Copyright [year] [client name]. All rights reserved.
''' ***********************************************************
''' Class.Method: IConfigProvider.GetSetting
''' summary
''' [summary goes here]
''' /summary
''' param name=name
''' [description goes here].
''' Value Type: see cref=String / (System.String)
''' /param
''' param name=defaultValue
''' [description goes here].
''' Value Type: see cref=String / (System.String)
''' /param
''' exception cref=System.ApplicationException
''' Thrown when...
''' /exception
''' returnssee cref=String /(System.String)/returns
''' remarksparapre
''' RevisionHistory:
''' -----------------------------------------------------------
''' Date Name Description
''' -----------------------------------------------------------
''' mm/dd/yyyy [logged in user] Initial Creation
''' /pre/para
''' /remarks
''' -----------------------------------------------------------

What next? Blood type? Mother's maiden name? Favorite color? It's ridiculous and detrimental to the code. Comments are supposed to make your code easier to understand and maintain-- not harder.

When commenting, there are a few essential rules I believe in:

1. The value of a comment is directly proportional to the distance between the comment and the code. Good comments stay as close as possible to the code they're referencing. As distance increases, the odds of developers making an edit without seeing the comment that goes with the code increases. The comment becomes misleading, out of date, or worse, incorrect. Distant comments are unreliable at best.

2. Comments with complex formatting cannot be trusted. Complex formatting is a pain to edit and a disincentive to maintenance. If it is difficult to edit a comment, it's very likely a developer has avoided or postponed synchronizing his work with the comments. I view complex comments with extreme skepticism.

3. Don't include redundant information in the comments. Why have a Revision History section-- isn't that what we use source control for? Besides the fact that this is totally redundant, the odds of a developer remembering, after every single edit, to update that comment section at the top of the procedure are.. very low.

4. The best kind of comments are the ones you don't need. The only comments guaranteed to be accurate 100% of the time-- and even that is debatable-- is the body of the code itself. Endeavor to write self-documenting code whenever possible. An occasional comment to illuminate or clarify is fine, but if you frequently write code full of tricky parts and reams of comments, maybe it's time to refactor.

Posted by Jeff Atwood View blog reactions

So you want to be a Game Developer Multiple /bin folders in ASP.NET

Comments

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.
Ned Batcheder on November 13, 2004 07:55 PM

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/).
Darrell on November 14, 2004 12:20 PM

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.
Jeff Atwood on November 15, 2004 01:41 AM

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.)

Wen Lai on November 15, 2004 10:23 AM

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.
Ihari on March 24, 2005 03:27 AM

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.
Jeff Atwood on March 24, 2005 03:30 PM

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.
Jeff Atwood on December 5, 2005 04:48 AM

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.
jef on January 4, 2007 05:23 PM

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.
}
steve on January 23, 2007 02:46 PM

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
nDoc CHM Generator on July 17, 2007 09:31 AM

I had trouble finding this information on the Internet!
Thank you for taking the time to post!
Pascale on April 30, 2008 10:27 AM

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.
nyb on July 3, 2008 06:40 PM

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.
Drealmer on July 25, 2008 02:16 AM

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.
FDG on July 28, 2008 03:50 AM

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.
Astrochicken on August 6, 2008 09:32 AM

The value of a comment is directly proportional to the distance between the comment and the code.

Surely its inversely proportional i.e. as the distance increases the value of the comment decreases?
Andy Johnson on November 15, 2008 10:59 AM

Hangzhou Deli technology production distribution a href=http://www.hztalent.com/Process-calibrator.htmlProcess calibrator/a products, providing a variety of process calibrator. Welcome to the Advisory parameters ...p
Paperless Recorder Low Cost Paperless Recorder,Supply a href=http://www.hztalent.com/Paperless-recorder.htmlPaperless Recorder/a#65292;Easy use,good quality!One of the best paperless.which adds XML comment support to the current version of VS.NET
sillui on November 19, 2008 07:34 PM

#20919;#36710;#36215;#21160;#21518;#65292;#28082;#21387;#25402;#26438;#26410;#27491;#24120;#24037;#20316;#21069;#36716;#36895;#19981;#33021;#19968;#30452;#36229;#36807;3000r/min #65292;#21542;#21017;#21487;#33021;#25439;#22351; #28082;#21387;#26426;#26500;#12290;#27792;#20110;#27969;#28689;#65292;#26080;#38480;#24230;#36148;#36817;#33258;#28982; #31361;#30772;#24120;#35268;#30340;#28020;#23460;#35774;#35745;#65292;#21462;#28040;#20102;#28107;#28020;#25151;#24120;#35265;#30340;#29627;#29827;#22260;#21512;#65292;#22312;#28020;#23460;#22320;#38754;#38138;#19978;#40517;#21365;#30707;#65292;#20960;#22359;#22823;#30707;#38543;#24847;#23433;#32622;#22312;#40517;#21365;#30707;#19978;#65292;#28020;#23460;#22681;#38754;#21017;#20197;#26412;#33394;#38450;#33104;#26408;#20026;#39280;#12290; Pneumatic fitting#19968;#20010;#21518;#20445;#38505;#26464;#25200;#27969;#26495;#12289;#20004;#31181;#19981;#21516;#31867;#22411;#30340;#20391;#35033;#21644;#21452;#25490;#27668;#31649;#65292;#21478;#22806;#36824;#26377;#19968;#20123;#30899;#32420;#32500;#37096;#20214;#21450;#21319;#32423;#21518;#30340;#19981;#38152;#38050; #28040;#22768;#22120;#21487;#20197;#29992;#12290;#25454;#19971;#29028;#20844;#21496;#19968;#20301;#39046;#23548;#20171;#32461;#65292;2003#24180;#20844;#21496;#23601;#36141;#20080;#20102;25#22871; #29028;#28845;#20998;#26512;#20202;#22120;#65292;#24182;#20998;#21035;#35013;#22791;#32473;#21253;#25324;#19996;#39118;#29028;#30719;#22312;#20869;#30340;#21508;#19979;#23646;#30719;#20117;#12290;#26174;#28982;#65292;#36825;#20123;#20202;#22120;#24182;#26410;#21457;#25381;#20316;#29992;#12290; #29627;#29827;#36716;#23376;#27969;#37327;#35745;#26159;#19968;#31181;#20351;#29992;#31616;#21333;#12289;#35835;#25968;#26041;#20415;#12289;#29992;#36884;#21313;#20998;#24191;#27867;#30340;#30636;#26102;#27969;#37327;#27979;#37327;#20202;#34920;#12290;
rq3r on December 14, 2008 11:44 PM

XML comments are a poor solution for a problem that was already solved. Javadoc is way better in clarity and gives the same benefits. For C++ theres Doxygen, which uses the same syntax as Javadoc (a great decision IMO) and partially supports other languages. MS should adopt this standard, not invent a new one. I don't see the need to structure and pollute the comments with XML.
Fabio Ceconello on December 28, 2008 06:09 AM
Name:

Website:

Enter the word
rhymes with..
(hear it spoken)

Your comments: (no HTML)

Content (c) 2008 Jeff Atwood. Logo image used with permission of the author. (c) 1993 Steven C. McConnell. All Rights Reserved.
Newer
Multiple /bin folders in ASP.NET
Older
So you want to be a Game Developer

Home

Browse All Posts

[ad] Reason #2 not to use SlickEdit: The office is so peaceful after 10 PM. Download a free trial!
[ad] Improve Your Source Code Management using Atlassian Fisheye - Monitor. Search. Share. Analyze. Try it for free!
[ad] Think code review sucks? Try peer code review with Code Collaborator – no meetings, no paper, no kidding! Also learn tips and tricks with this free book.

Count of RSS readers
Traffic Stats

About Me
Subscribe in a reader
Subscribe via email
StatCounter - Free Web Tracker and Counter

HAHA on January 31, 2009 5:43 AM