Visual Studio Toolbox

Doing Visual Studio and .NET Code Documentation Right

Good documentation is important for any application, and it starts with documenting your code. It helps you and it helps your users.

• By Terrence Dorsey
• 02/21/2017

It's no secret that I believe documentation is a crucial element of quality software -- and not just because I've spent most of the last 25 years working on end-user and developer documentation. We've all written code that works perfectly fine for us, because we wrote it, but other users need help knowing what it does and how to put it to work.

Hey, I bet you've even written code that, six months later, you forgot how it works ... and now you'll spend the better part of a day relearning the code you wrote in the first place.

It happens all the time and I've seen it over and over. Creating even the most simple documentation -- notes in work tickets, comments in code, a README file -- helps us remember what we created, how it works, and why we coded it that way months later after we've written thousands of lines of completely unrelated code. Or when the colleague who wrote that code leaves the team and now you're responsible for maintaining it. Or someone wants to use the code from your repository and keeps submitting issues asking questions about it...

The answer is to create some documentation for your code, preferably good, comprehensive documentation. Here are some tools and advice to help you get the job done.

README First
If you do nothing else, at least create a README file that provides basic information about your code or project, how to build or invoke it (if executable), and license or copyright details. GitHub can create a README.md file automatically for a new repository and displays it by default, with formatting, in your repo page, so there's little excuse to skip this simple step.

What should be in your README beyond the basics?

Jesse Luoto has written a simple yet incredibly handy Readme Best Practices: Best practices for writing a README for your open source project page, as a README.md file, with a default README outline that you can clone directly into any new project, and it's all provided as "free and unencumbered software released into the public domain".

Need some more ideas for an even better README? Stephen Whitmore created Art of README: Learn the art of writing quality READMEs. While written primarily for authors of Node.js modules, the advice offered is applicable to any software project written in any programming language (and there are translated versions of Whitmore's advice in Chinese, Brazilian Portuguese and Spanish.) From an outline of recommended document formatting to advice on writing and links to good examples of READMEs, I highly recommend taking a look at Art of README and incorporating it into your own projects.

You'll find a slightly different, but very interesting approach, in Besir Kurtulmus' article How to Write a Good GitHub README Using Data Science over at Algorithmia.

Kurtulmus surveyed the README files from 1,000 GitHub repositories for each of 10 different programming languages and ran them through a machine learning algorithm to evaluate what makes a good README. Want to see how yours stacks up? You can run any repo through the GitHub README Analyzer by Algorithmia. XML Code Documentation

For .NET Framework development, particularly in C#, XML Documentation Comments are the officially sanctioned way to document your code with the ability to automatically create documentation files from these comments at compile time.

You could create XML documentation comments manually, but you don't have to. Atomineer Pro Documentation for Visual Studio is one of the tools available to parse your code as you write it and automatically create relevant XML comments. It even revises comments on-demand after you make changes to your code. Atomineer also supports Doxygen, Qt and JavaDoc code documentation formats, which I'll get to in a minute.

Sandcastle Help File Builder (SHFB) provides a standalone graphical application, Visual Studio integration package, and MSBuild tasks to generate help files from XML documentation comments. Sandcastle originated in a Microsoft project, but ongoing development is now overseen by Eric Woodruff. This is a free, Microsoft Public License (Ms-PL) with really excellent documentation to get you started building your own docs.

NDoc is an older tool for generating class library documentation from your code assemblies and XML comments. This project hasn't been updated in quite a while. Development continued in a successor project, NDoc3, but that doesn't seem to have been updated since 2013. These projects did, however, provide the basis of some other, newer tools, so I'm including them here for reference purposes.

Docu is a .NET Framework XML code documentation landscape that is meant to be very simple, producing only static HTML content from your code, making it very easy to host or distribute.

AutoHelp is a similar documentation generator, providing a very simple engine to read your assemblies and XML documentation to create help files. The key with AutoHelp is the output, which uses ASP.NET MVC 5, ASP.NET WebApi, TypeScript, JQuery and Bootstrap to build your documentation as an attractive, modern web site.

VSdocman is a commercial tool that integrates with Visual Studio to provide automated XML comment creation and editing, help file generation, and even class diagram generation. VSdocman supports Visual Studio 2005 through 2015 and there are generator versions for C#, Visual Basic .NET, and Visual Basic 6. There's a 14-day trial and licenses for individuals or teams.

SubMain's GhostDoc is another commercial tool to help you create and edit XML comments and generate help from your comments and code. In addition to the usual features, GhostDoc Pro and Enterprise include configurable document templates, a code spelling checker, Documentation themes, previews, and more. There is a free version of GhostDoc along with single-purchase licenses and yearly subscriptions for Pro and Enterprise features.

Oleg Shilo's DocPreview does something really simple, giving you a quick preview of a single XML code comment block within Visual Studio. No need to compile your code, just preview and make any necessary edits right there.

A similar tool from Travis Illig, CR_Documentor is a CodeRush plug-in for rendering XML comment previews within Visual Studio.

More Code Documentation Tools
There are some other established formats for code documentation, and toolsets that can generate help files from those formats as well as XML comments. Here's a quick overview of those tools.

Doxygen picked up where the NDoc projects left off, and has developed into a highly configurable, flexible code documentation tool for a variety of languages including C/C++, Objective-C, C#, PHP, Java, Python, and others. While primarily developed for Linux and Mac OS X, there are binaries for Windows and the entire project is open sourced under the GNU General Public license. There's extensive documentation for the project.

DoxygenComments, by Oleksandr Manenko, is a simple helper extension for Doxygen that highlights code comments for editing. Oracle's Javadoc comment formatting and toolset is a standard for Java development (no surprise there), and is also the primary code documentation format for some API documentation toolsets.

Finally, QDoc is a comment format and toolset originally designed for the Qt embedded device development framework. I don't think it's widely used outside of the Qt community, though it's worth knowing about if you do embedded or mobile device programming. To learn more, see Introduction to QDoc on the Qt site.

Useful Code Documentation Extensions
Here are a few more tool and extensions that will help you with various code documentation tasks.

Liangying Wei's Docascode Project is a code documentation generator that uses the DocFX Metadata Format Specification to create YAML-format language metadata that can be combined automatically with separate HTML, Markdown, or plain text conceptual documentation topics to create a static documentation web site.

DocStubsJs, by Michael Obermeyer, automates some of effort of generating JavaScript and TypeScript code documentation comment stubs. You just type "///" for VSDoc or "/**" for JSDoc and DocStubsJs parses the surrounding code to determine whether to add a new comment line, create a documentation comment stub, or do nothing.

Most of the tools I've suggested so far use code comments as both internal code documentation the source material for generated external documentation. Remarker, by Gil Yoder, is a clever extension that customizes your comments in Visual Studio by using keywords and Markdown-like markup. Your comments can be resized, color-coded, and even decorated with strikeouts. It even works for multi-line comments.

The Glossary extension for Visual Studio lets you add a glossary of terms to your solution. Specifically, what it's really intended for is providing an acronym-to-term glossary, but I don't see why you couldn't use it for term-to-definition lookup as well. This is actually far more important than you might think: UX testing has shown that even sophisticated users can be confused by terminology substitution, such as the use for shorthand naming and acronyms. Be clear and consistent!

Here's another really neat tool: Whole Tomato Software's SourceLinks is a free Visual Studio extension that helps you link source file comments to related information in issue trackers like FogBugz, source control systems, external documentation sources, and more. It's highly configurable to incorporate custom data sources. I just think this idea is great. It would have saved a lot of chasing down information on some projects I've worked on.

Finally, looking up documentation is important, too -- I spend as much time looking things up as coding some days! Search In Velocity, by Jamie da Silva, is a Visual Studio extension for searching documentation sources in the Velocity offline documentation viewer for Windows. No need to fire up yet another browser window -- assuming you're online and have decent connectivity. Just press Ctrl+F1 and search within dozens of documentation sets, from ActionScript to Unity3D and more.

More Tools and Information
That's a lot of information and resources for documenting your code, but there's more out there. For starters, take a look at my September 2014 column Web API Documentation Tools in Visual Studio Magazine for tools that document how others can use your application APIs.

Got a favorite code documentation tool that I didn't cover here? Let us know in the comments. I like to circle back occasionally and update these round-ups with tools our readers love, so tell me about the tool and how it helps you.