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

Perfect Storm

A perfect storm is a combination of events that result in a huge change to the environment.

My codeplex project Perfect Storm is intended to be a collection of software parts that each may be used independently yet become very powerful when used in concert.

The first part written was a xslt based code generation suite.

Further additions have included:

  • A set of smart types – primitives that know their previous state and can detect whether a value has been set.
  • A model base class that adds to the smart types using the composite pattern along with an associated navigator class that allows xpath querying of your object tree (this is far stronger than linq which assumes a list structure).
  • A lightweight class loader.
  • An interface to the rules engine of the workflow foundation.

I have recently been expanding the model types to implement INotifyPropertyChanged to assist in is use as the view model component in the M-V-VM pattern used by WPF. Given that this library was designed to work with winforms (which can also use the INotifyPropertyChn) the changes were limited to extensions.