Javadoc comments considered evil : how to use xDoc without them

I have recently moved to a new project.
This means that there is a large code-base that I need to learn quickly.

One of my starting points was to try and point a NDoc type tool at the application.
It was at this point that I found that the application was missing at least 5000 XML comments – the NDoc tools typically use the .
When I started to add them to the units that I was working on I was pointed to an article that describes javadoc style comments as now being considered evil for an internal project.
Agile projects these days use self describing names so “empty” xDoc comments don’t help.

I have suddenly realized that I can use reflection to create the “empty” xml stub file from an assembly.  This would allow me to get the documentation (that will be at least partially useful) without polluting the code with javadoc comments.

One of the things that I like xDoc tools to generate is a class hierarchy diagram.  This is great for finding the descendent’s of a class that you are modifying (this documentation is especially useful if you have code that currently does not compile).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s