Of course the above is a complete lie. In a shocking turn of events, developers HATE documentation. (Good developers, that is.) That’s because, 1) it’s tedious and painful, 2) programmers prefer to write code, and 3) comments get so easily out of synch with the code.
Unless you can document your code in VS2012 directly and have it truly self-update, it’s just not going to get done, and whatever you DO get done will be worthless and obsolete as soon as it’s written.
Yet, if you want to grow a team’s maturity and not get bogged down in maintenance, you need to have code that’s not siloed and where problems that come up can be easily knocked down. This means SOMETHING needs to be written down without costing weeks of time better spent, I don’t know, PROGRAMMING. What to do?
In the past, we would have dumped out some generic documentation in a wiki and called it good. Then any new programmer on the team would have to go through a deep-end-of-the-pool learning period of weeks to months – much longer than really necessary to master what’s done. I think we’ll always have that ramp-up period, but it’s less easy for us to ignore adding some basic documentation on our code in VS2012.
I will say, categorically, you do need an auto-generated documentation set for your coders. Why?
- Unless it’s easy/effortless, it won’t get done.
- It automatically keeps your documentation up to date when parameters, return values and exceptions change.
- Its picked up in Intellisense in VS – so when I call a method it’ll let me know WHAT the app is intended for and how to use it.
- It encourages higher quality code
- Makes it easier to implement (and pass) Code Analysis’ stringent naming conventions.
There’s a couple of ways of going about this. Once you have extensive XML documentation created in your code, you can compile it with a /doc param to generate document XML.
This is then readable in a variety of formats (Doxygen, which MSFT doesn’t seem to like, or Qt or JavaDoc. MSFT seems to like SandCastle, http://shfb.codeplex.com/). I like VSDOCMAN at http://www.helixoft.com/common/buy-helixoft-products.html, but it’s $229/license. Really NOT worth it! )
The route I’m discussing below gives you professional looking MSDN-type documentation that is functionally complete (and like MSDN a good drillthrough on a API but never a comprehensive one-stop-shop). So it’ll never take the place of a 2-5 page overview/summary doc and it won’t be on the same 50,000-foot level as a UML diagram but it will give your clients more assurance than “our code is self-documenting” and give good coders a place to start! (more “why to buy” reasons are on the atomineer FAQ pagehere.)
Adding Documentation to your Code Set
The great news is you don’t HAVE to buy anything. You can quickly and easily add documentation to any class or method type just by entering “///” above a method. However, Atomineer makes a good product, and it’s cheap at $10/year… See this post… it is really a no-brainer.
Adding three whacks to it – even without buying any add-ons- creates a very nicely formatted XML segment that can be auto-extracted and converted to a CHM help file.
Like all good code, this page abstracts out a good deal of complexity. It’s hard to get a comprehensive picture of what’s going on by just reading something like this:
private msgs.Environment[] GetEnvironmentCollection(string envConfigWebApp,
string envConfigListName)
{
msgs.Environment[] returnEnvironments;
//get environments
using (var environmentModel = new model.Environment(envConfigWebApp, envConfigListName))
{
var environments = environmentModel.GetAllEnvironments();
Atomineer has a 30-day try before you buy. And, since you can document by file (vs by method, by hand, painstakingly) and it offers auto-updates, that is kinda a no-brainer. In the setup, which is painless, three options on the doc format exist:
I installed it with most of the defaults – didn’t like the Doxygen formats.
Now when I open up a class and r-click I get a document format option>….
And under Tools, Atomineer I see the following options:
So let’s try documenting the entire file. Ctrl-Shift-A, Ctrl-Shift F …
It stubs out the documentation for us, which is cool.
So, that gets us (hopefully) 95% auto-generated and auto-updated documentation. How do we extract it out? Let’s try installing Sandcastle (http://shfb.codeplex.com/)
I don’t know what MAML is, so I’m leaving it off for now.
It’ll ask you if you want HELP2 – that’s for VS2008 and previous. Click no.
You do do want to install the SandCastle Help File Builder.
At this point, you’re almost there. You can create a new project and add it to the solution, and add references to the SandCastle dll and your project dll (under Add Documentation Source).
So, I’ll start with an easier service class. I stubbed out some documenttion, and then in the Buld properties of the project I selected a XML file:
Now I restart my system and open up the Sandcastle Help File Builder. (There is a useful Getting Started guide here: http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/b772e00e-1705-4062-adb6-774826ce6700.htm)
I select the DLL that just built in the BIN file of my project – binSafeData.XML.
I add a reference in the project to the SandCastleBuilder.Utils.dll assembly, in C:Program Files (x86)EWSoftwareSandcastle Help File Builder
Then, from the menu, I select Documentation, Build Project. After it builds … which takes a while and is resource intensive (Here is where the errors we saw earlier in our build comes to bite us right in the rear end. There’s going to be a lot of missing/incorrect refs in the CHM file) – select Documentation | View Help File.
(This errored. Opening up the file generated in the build notes –c:_TFSSandCastle_TesterHelpWorkingOutputHtmlHelp1Documentation.chm)
… and that didn’t work either. I imagine this CHM file could be embedded with your project, However, pulling up the Index.html file from C:_TFSSandCastle_TesterHelpIndex.html gets me this:
Below are my nicely documented (and automatically updated) comments and witty remarks.
As you can see, you can drill in on the members – but the value of it is exactly what you put into it. As a developer, more verbose documentation – especially not the “what” but the “why” – directly leads to a better learning curve for the guys after you.
Appendix – UML diagrams and documentation
We can’t forget about the automatic UML diagram methods available to us in VS2012 to help us visualize this codebase. R-click anywhere in the class and select Generate Sequence Diagram – which can then be saved with the project if desired:
Also, in VS2012 on the top menu you can select Architecture, Generating Dependency Graph to get a better view of code dependencies. (The red X’s are because the projects aren’t in a buildable state currently – missing assembly refs to Microsoft.SharePoint for example):
The great thing is, I can click on those generated dll’s and drill through to the internals themselves to get an idea of the process flow:
Also under Architecture there’s a new UML Model Explorer and an Architecture Explorer. I haven’t had time to explore these and I’m not sure how useful they really are yet.