9 Tips for Simplifying Your Code Documentation

Documenting your code is important. It tells other developers what the code does, why it is constructed in a certain way, and how to use it. Good documentation saves them time when they are trying to perform a certain task that isn’t straightforward. It will probably also save you time?because the human brain can only store so much information. Even your own code will confuse you at some point in the future.sp

Even though code documentation is important, many developers find it tedious. This is exacerbated by the fact that many companies associate code documentation with long Word documents that must be kept up to date manually. Not exactly developer heaven.

So how can we simplify code documentation while still keeping it effective?

Add Documentation to Source Control

An easy starting point is to put your documentation under source control. This will allow your documentation to evolve together with your code. It will also give you a log of what changed and, if you’re using descriptive commit messages, why it was changed.

One thing you should try to avoid is storing the documentation?only on a network drive. You’ll lose all the advantages of a good version control system, like

• seeing who changed what, why they changed it, and when they changed it;
• seeing the difference between two versions with a diff tool;
• being able to create branches with new features and accompanying documentation; and
• allowing team members to review the documentation before merging it to the master branch.

I once worked for a client that required putting the documentation in?a Word?file on a shared network drive. To make my life easier, I put my documentation in Markdown files and put them under source control. I then set up my CI build to automatically transform the Markdown files into a Word document using pandoc. This Word document was then automatically copied to the shared network drive.

With this solution, I didn’t have to remember to copy the Word document over, which I often forgot, and I could have my documentation in source control.

This brings us to another important way to simplify your documentation: automate!

Automate Manual Labor

Inevitably, you will have to type documentation manually and keep it up to date. But a good portion of the documentation process can be automated. There are many tools out there that help you generate documentation. In the old days, there was only the Sandcastle Help File Builder?which is apparently still being maintained.

But I would argue there are better options now. A tool like Swashbuckle or NSwag can automatically generate Swagger documentation based on your existing code. DocFx can help you generate documentation based on your API and/or Markdown files. GitHub Pages?or Read the Docs can host your documentation with minimal effort required on your side. GhostDoc will help you generate and validate your XML comments and create help files, all automatically.

As you can see, there are multiple tools to help you generate documentation that is easy to use. You can focus on writing the documentation while the tools help you with the ceremony around it.

Document Just Enough

Another easy way to simplify your documentation is to cut back on it. Many companies fall into one of two extremes: they have hardly any documentation, or they have documentation just for the sake of having it. The latter is often required by managers who are afraid knowledge will be lost and see documentation as the only way to prevent that. So their solution is to write lots of documentation. This leads to a situation where the valuable documentation is lost in the noise surrounding it.

Start by making your code is clear and readable. Make it discoverable by adding XML?comments. Only if something needs more context, is very complex, or requires the bigger picture to make sense should you write more lengthy documentation. And when you do, try to have as little overlap as possible with other pieces of documentation.

Don’t Make One Big Diagram

I’ve seen teams print out many pieces of paper and stick them together on the wall to create a big diagram of all classes or tables in the application. When an application reaches a certain size, such a diagram provides little to no value. It’s often too large, contains too many lines between the various parts, and is never up to date.

Start by providing a general sketch of your code. This could be a diagram portraying the context in which your application runs, like calls to other services, incoming data, etc. Or you could draw an overview of the various components of your library. You can then take the pieces in said overview and drill down, providing more detailed documentation of the various parts. Finally, at the lowest level (i.e., the class or function level), you can pick out some complex pieces and write or draw documentation for them.

One word of warning, though: if you find yourself needing to explain a piece of code, see if you can write the code in a more readable way first. Often, complex code can be rewritten such that it no longer requires documentation. The code then documents itself.

Guide Your Visitor

When separating your documentation into different documents, provide links to guide the reader. If you’re writing Markdown files, link to the relevant files when you mention certain subjects. If you’re using XML comments, use cref to link to other classes and members. Have a central navigation to point the reader to the different parts of your documentation.

Write Your Tests As Documentation

Well-written tests will also provide some documentation. Compare this:

[Fact]
public void CalculateTest01() {
    // some test
}

To this:

[Fact]
public void Calculate_WithNullValues_ShouldReturnZero()
{
    // some test
}

If a developer encounters the first, she might be puzzled and need to investigate further. She will need to read the test to understand the functional requirements. In the second example, she will only have to read the test, not the implementation, for it to be clear how the code behaves.

Use XML Comments

XML comments is an underused feature in many teams and companies. Yet it is such a simple way of communicating what your code does. XML comments are what IntelliSense shows in Visual Studio when you’re writing code. They allow a developer to quickly read what a method does, what its signature is, and what each parameter is, instead of the developer having to navigate to the method to learn this information.

Take this for example:

public class ObjectAmountJsonConverter : JsonConverter {}

When you use this in Visual Studio, it looks like this:

Now, let’s add some XML comments:

/// <summary>
/// Converts an Amount to and from a JSON object, with two properties: value and unit.
/// </summary>
public class ObjectAmountJsonConverter : JsonConverter {}

This is now what a developer will see in Visual Studio:

A lot more clear, isn’t it? This is a very easy way to communicate to the consumer of your code.

Remove Comments in Code

Putting comments in between lines of your real code is a bad way of documenting your code. I’ve written about commented out code before. Many of the points made there are valid for comments documenting your code too. Basically, comments in code distract developers and lead to code rot, i.e., they become unmaintained.

The article also points out some useful alternatives to comments in your code, because just removing them might make you a little nervous.

But aren’t XML comments subject to the same dangers? Well, not really. First, they don’t distract because they aren’t cluttered around your actual code. And second, there are tools like ReSharper and GhostDoc that show you XML?comments that no longer match the code.

Granted, these aren’t rock-solid guarantees. But there are still far greater benefits to using XML comments than to using comments in between your regular code.

Use a Source-Control Friendly Format

You can’t document everything in XML comments, so sometimes you will need to write up a real document. At many companies, this often means using Word documents. The big disadvantage of Word documents is that they don’t integrate nicely with source control.

Sure, you can add them to source control, but your built-in diff tool won’t be able to show the differences, making it hard for you to see what changed. A better idea is to use a format that is pure text. The ideal candidate is Markdown, as it provides predefined formatting rules for things like headers and lists but is still very readable as pure text.

Don’t Stress

If you take these tips into account, writing documentation will no longer be a stressful chore or something you just never do. Use the tools that are available to make your life easier, automate as much as possible, and keep it simple. The users of your project will be very thankful.

Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.

About the author

Peter Morlion

Contributing Author

Peter Morlion is a passionate programmer that helps people and companies improve the quality of their code, especially in legacy codebases.? He firmly believes that industry best-practices are invaluable when working towards this goal.

This author does not have any more posts.