Creating a list of TODO's

  • Thread starter Thread starter K Viltersten
  • Start date Start date
K

K Viltersten

Is there a facility in VS allowing the
programmer to find and list all "TODO"
locations in the code?

In C++ i had this "\todo text" which
resulted in a list of things todo as
a separate HTML file upon run...
 
K Viltersten said:
Is there a facility in VS allowing the
programmer to find and list all "TODO"
locations in the code?
Click to expand...

In the "View" menu, select "Task List", and then in the Task List window,
use the dropdown to select "Comments". This should bring up a list of al the
//TODO comments. Double-clicking in any of them will jump to the location in
code where it is written.
 
K said:
Is there a facility in VS allowing the
programmer to find and list all "TODO"
locations in the code?
Click to expand...
Well, first of all, there's the Task List (View -> Task List). For comments
it only works on the currently opened file, but it works across files for
shortcuts (Edit -> Bookmarks -> Add Task List Shortcut). This requires
manual maintenance, though.

Then there's the obvious "Find in Files" (Ctrl+Shift+F). You can copy+paste
the output of that.
In C++ i had this "\todo text" which
resulted in a list of things todo as
a separate HTML file upon run...
Click to expand...
Automatic generation, on the other hand, is another matter. If it's
important that this is done at every build, you can use a post-build event
to hook up a batch file that will search all files (a simple FINDSTR should
do). VS doesn't really have a facility for this, unless you count XML
comments (which still require a separate doc generator).
 
In C++ i had this "\todo text" which
VS doesn't really have a facility for this,
unless you count XML comments (which still
require a separate doc generator).
Click to expand...

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?

2. Is it a good idea to go in depth with
the XML commenting and adapt it seriously or
is it rather sparely used?

Thanks for the answers, by the way.
 
K said:
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?
Click to expand...
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).

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?
Click to expand...
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.
 
Jeroen Mostert wrote:
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.
Click to expand...

Just need to ask... are there that many tools? The two I know of are
NDoc and Sandcastle, and NDoc is dead, and Sandcastle ought to be, are
there any others?
 
Lasse said:
Jeroen Mostert wrote:


Just need to ask... are there that many tools? The two I know of are
NDoc and Sandcastle, and NDoc is dead, and Sandcastle ought to be,
Click to expand...

Oh, come on. It's still in the early stages. It's slow and ponderous, but it
does get the job done.

You can still use the alpha build of NDoc for .NET 2.0 if you're so
inclined, which is at least faster.
are there any others?
Click to expand...
Serious projects? No. The rest is all incidental stuff (and most of it died
when NDoc came around). Visual Studio .NET actually had its own rudimentary
documentation builder (Tools -> Build Comment Web Pages), but this feature
wasn't carried forward.
 
Doxygen?


I'm no expert on Doxygen but when we
used it for our C++ project, the
comments needed to be like:

/** A method that is SOOO cool.
\param input parameter in
*/

and that it wasn't possible to use
XML comment system at all. Is it
still true?
 
Doxygen?


Also, have the issues with partial
classes and other minor problems
been resolved?
 
Back
Top