Static Code Analysis and API Documentation

Documentation is increasingly important for maintaining a codebase. As your team grows and developers have to interact with existing libraries, comprehensive documentation can help them ramp up. If you aren’t currently documenting your code, you should start today. To do this in Visual Studio (2005/2008) [I think this also works for 2003 if you are using C#]. 

  1. Right click your project file, go to properties
  2. In the build tab, ensure the XML Documentation file is checked.
  3. As you are developing, use the triple comment (/// or ”’) above any class or method. This will automatically expand to the method signature
  4. Add any additional XML fields such as Example, Exception, See, SeeAlso
Notice that this automatically builds the signature of the method you are commenting. This is very handy for new developers on your project as they will see your comments in the intellisense provided by Visual Studio. I think this is very important as a way to identify code smells. As you are reviewing or developing, look at where your comments are. If they are describing methods this is decent encapsulation. If your methods have documentation in the middle your code can likely be refactored.

How can we get even more mileage out of those comments? Sandcastle is an application made of MSBuild scripts along with Xsl and a some other helper scripts that will parse your XML documentation from Visual Studio and create a CHM (Compiled Help), or MSDN-style documentation website. This is handy for explaining your code to stakeholders who do not have Visual Studio. In addition to non-technical stakeholders reassurance, IT staff supporting the system years from now will have an easier time debugging your system with the well-prepared documentation provided.

Leave a Reply

Name *
Email *