Tag Archives: documentation

Improving your code quality through documentation

I believe that it’s readily possible to improve the quality of your code by documenting it as you go along. It’s a given that in order to create any documentation at all in the .NET environment that developers have to add XML comments, we should all be familiar with how to add them so I’m only going to point you in the right direction of you don’t already do this: http://msdn.microsoft.com/en-us/magazine/dd722812.aspx

Although adding comments is the first step you really shouldn’t stop there. Those comments can be easily and automatically turned into documentation with every build. Third party tools that turn your XML comments into nice looking and formatted documentation that also integrate with Visual Studio are readily available.

Personally I’m using Sandcastle Help File Builder (SHFB) as it’s well established, builds Microsoft lookalike documentation, and, most importantly, is free so there’s no need to justify any expense with the boss.

The advantage in using a tool is that you can then make sure that your documentation is developed along with your code. Which has its own benefit of improving the coverage and quality of your documentation and also has a secondary effect on improving the quality of your code as you not only need to think about getting the code working but also about understanding and communicating its purpose to others. Thus documenting your code becomes a way of reviewing and improving it. The mistakes you catch during the development phase saves your time threefold as compared to fixing it during testing or after release.

If you’re not using the documentation tools as you go along then not only is the documentation less likely to be created in the first place but it can be seen as a last minute chore and thus less effort is put into it and as a result the quality is not as good.

Anyway, enough justification, you’re already with me or you’ve stopped reading at this point. Here’s how to add ongoing documentation with Sandcastle Help File Builder (SHFB).

First, install SHFB from here: http://shfb.codeplex.com/. The installation instructions are here: http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/8c0c97d0-c968-4c15-9fe9-e8f3a443c50a.htm you should use the ‘Guided Installation’ as it’s very easy. This will include a ‘Visual Studio Integration Package’ that allows you to create and build the documentation project within Visual Studio. However there is also a Sandcastle GUI for developing projects separately.

Once it’s all installed open up Visual Studio and your development project. Add a new project, select the newly added Documentation category, select ‘Sandcastle Help file builder Project, set a name and location and click OK.

Sandcastle works be reading the compiled DLL/EXE, extracting the XML Comments, and applying templates to turn them into documentation. This does increase the total build time, especially the first time you build the help project. The Documentation Sources folder in the help project lists which DLLs/EXEs are read. You add a DLL/EXE by right clicking the Documentation Sources folder and selecting Add Documentation Source, browse to your build folder, select your DLL/EXE and click OK. Now try a build.

By default SHFB is set to create a CHM documentation file, this will be created in a Help folder under the project folder but like a bin folder it is not included as part of the project. To see your documentation click on the Show All Files button, navigate to the .chm file and double click on it.

Marvelous isn’t it, you just saved yourself weeks of fiddling about with Word. If you’re smart you made sure to estimate the documentation phase as at least three weeks long so now you’ve got plenty of time to jet of to the Bahamas and indulge your Bond fantasies as you ‘work from home’.