Re: SV: Creating a list of TODO's
- From: Jeroen Mostert <jmostert@xxxxxxxxx>
- Date: Sun, 23 Mar 2008 22:38:38 +0100
K Viltersten wrote:
Bit of both, actually. There's a baseline set of tags used by everyone and documented in the MSDN, some of which actually come with generated Intellisense (like <summary>) and compiler support (like <param> and <seealso>, where the compiler will verify that you're referring to existing parameters/types).In C++ i had this "\todo text" whichVS doesn't really have a facility for this, unless you count XML comments (which still require a separate doc generator).
resulted in a list of things todo as
a separate HTML file upon run...
I've been hearing "XML comments" mentioned
a number of times. I'd like to get your opinion on this.
1. Is there a standard of commenting using
XML or is it rather "every one does as one
pleases"? Several competing standards?
Then there are minor extensions like (<langword>) that are widely supported but not exactly standardized, and finally it's always possible to just invent your own tags for specific purposes -- like <pre> and <post> if you want to annotate your source with pre- and postconditions.
Almost all tools out there that process XML documentation are flexible enough to allow you to specify your own tags and how they should be processed, so there's little competition going on, really.
2. Is it a good idea to go in depth with the XML commenting and adapt it seriously or is it rather sparely used?Depends on what you're trying to achieve.
First of all, XML comments are just a good idea if you're writing a library, or in general any sort of code that's going to be used by other people, since it allows you to
- Provide good Intellisense support: see the use and purpose of a method or enum value as you're typing;
- Add special usage notes or semantic restrictions that aren't expressible in code;
- Specify what argument values a method accepts, the exceptions it can throw, and under what circumstances it throws them.
And this is in addition to the standard <summary> documentation that allows you to explain what things do in the first place. Your documentation may actually be more extensive than what XML comments can provide (tutorials, samples, broad overviews, etc.) but XML comments should definitely be a part.
Whether you should be creative in adding your own tags, that's another matter. The baseline set of tags is actually pretty extensive, and there aren't that many cases where you'd really want to add your own semantic information (the pre- and postconditions I mentioned would be one, if you do programming by contract). However, XML comments are flexible enough that you can actually do this without much fuss -- if you often need to cooperate with other developers on code that's incomplete, for example, <todo> might come in handy.
If you just need to search on TODOs without the rest of the documentation, on the other hand, XML comments aren't any more handy than regular comments, unless you write your own processing tools.
--
J.
.
- Follow-Ups:
- Re: SV: Creating a list of TODO's
- From: Lasse Vågsæther Karlsen
- Re: SV: Creating a list of TODO's
- References:
- Creating a list of TODO's
- From: K Viltersten
- Re: Creating a list of TODO's
- From: Jeroen Mostert
- SV: Creating a list of TODO's
- From: K Viltersten
- Creating a list of TODO's
- Prev by Date: UnauthorizedAccessException writing to Windows (Vista) directory and writing to Registry
- Next by Date: RE: UnauthorizedAccessException writing to Windows (Vista) directory a
- Previous by thread: SV: Creating a list of TODO's
- Next by thread: Re: SV: Creating a list of TODO's
- Index(es):
Relevant Pages
|
