Code Documentation: The Complete Beginner’s Guide

You’re a little way into your first programming job, and things are getting easier. At first, all the code you had to deal with might have overwhelmed and confused you, but you’re starting to get the hang of it. That’s great! Now you’re wondering how to make the code you write to the next level. While there are lots of things to learn about your programming stack, many of which will make you a better programmer, there are a few that will serve you no matter what stack you work in. One of those is code documentation.

Many developers don’t write enough documentation, either because they don’t see the value or because they feel like they don’t have time. You don’t need to be one of those developers. With a little time and a lot of practice, you can add documentation for your code that makes reading it a?joy to use?for both you and anyone else who comes along.

Good Documentation Comes in Many Forms

When most developers think of code documentation, they think of?comments. Comments can be valuable additions to code, but they’re not the only definition of documentation. Documentation is anything you write in addition to your code to help someone else understand how it works. You might not think of it this way, but a good example of code documentation is a README file. A good example of basic documentation is the?Express.js?README file. It answers several important questions about the framework and tells you how you can include it in your project, how to install it, and how to run tests.

Good documentation can come in the form of API documentation too. Once again, Express.js provides a?great example. This version of the documentation is more of a reference library for developers using the framework. You’ll find answers to questions about what individual functions do and what different parameters to those functions mean. Without that quality documentation, Express wouldn’t have nearly as many teams using it as they do.

And of course, you can use in-line comments to document code too. Those kinds of comments usually aren’t used to teach people outside of your own team about the code. Instead, they’re useful to explain what’s happening in a particular bit of code to your teammates or to your future self.

Why You Should Document Your Code

As noted above, many developers don’t understand the purpose of code documentation. They’ll argue that good code should be self-documenting and that you shouldn’t need to explain it. These people are, in a word, wrong. The truth is that good documentation is an essential part of any codebase. Why? Because people?shouldn’t need?to read all of your code in order to understand what it does. “People” in that previous sentence can refer to anyone, including your future self.

The truth is that often, the “people” who’ll need to understand code after it’s written is you. That little bit of logic that seemed so clever when you wrote it six months ago might be difficult to understand today. If your code is well-documented, you don’t need to spend time trying to understand what it does. You’ll be able to spend a few seconds looking at the description and then get back to what you’re working on right now.

If you’re lucky enough to be working on code that’s used by dozens or hundreds of developers, good documentation is even more important. Your users’ lives will be significantly improved by your time spent writing good documentation, and they’ll thank you for it. Literally!

The key to remember is that?good documentation?saves more time than it takes to write it. It might be your time, or it might be the time of team members or even people you’ll never meet. Sometimes, writing documentation will even help you recognize a part of your code that’s too complicated so you can simplify it.

Some Common Documentation Mistakes

As a junior developer, you’re going to have to spend time learning what makes documentation effective. The good news is that you can learn from people who’ve gone before you so you can avoid common mistakes.

Under-Documentation

One common mistake I see with code documentation is to document information that’s already clearly visible. For instance, lazy developers will add “documentation” to a function by adding a block that provides the name of a function as well as the names of each parameter and their individual types. This type of documentation is useless! It takes seconds for someone to read the name of the function and the parameters it takes. That’s not documentation, it’s just repetition. Instead, the documentation should include a?quick bit of information?about what the function does and how each parameter changes the function’s behavior or why it’s needed.

Over-Documentation

The opposite pattern can also be a serious problem. To avoid writing too little documentation, some developers like to write out the explanation for every tiny bit of logic that’s contained in a function. They meticulously document every rationale that went into creating the function. By the time they’re done, they might have spent as long writing the function as they did writing the documentation. What’s worse, the documentation is often difficult to understand and takes just as long as reading the code. That kind of documentation is also a waste of time. Instead, good documentation gives a basic explanation of both the what and the why. If there are any particularly tricky parts of the code to understand, then documentation should explain just those parts.

Relying on Tests to Document

Occasionally, you’ll run across someone who argues that the best form of documentation is?unit tests. That approach has a major shortcoming: reading unit tests is often just as difficult to do as reading code itself. Any developer wishing to learn what your code does will have a big first step while they hunt down and read all of your unit tests. Many will just give up before achieving what they set out to do. While unit testing is a valuable addition to any codebase, it’s not a replacement for good documentation.

Ways to Take Documentation to the Next Level

If you work on a big code base, code documentation can feel daunting, especially if you haven’t been diligent about documenting code up to this point. It might feel like you’re trying to boil the ocean. If you have a big code base or one where you know good documentation is critical, you might want to investigate automated code documentation tools. These tools drastically simplify the process of writing consistent, good documentation for an entire team. A tool like?GhostDoc?will intelligently look at your code and use templates established by your team to kick-start your documentation with a couple of key presses. Automated documentation tools remove one of the other common reasons to oppose writing documentation: it takes too much time.

Once you have consistent documentation, other tools enable you to share that documentation easily. Automated documentation tools take the pain out of developing good documentation for things like public APIs that your code provides.

Get Started Today

Writing great documentation is a lot easier than writing code. Unlike code, documentation isn’t an all-or-nothing enterprise. Start with a goal to write good documentation for one function every day. That kind of practice builds healthy habits, and you’ll see the payoff down the road when you spend a lot less time trying to understand parts of your codebase. Over time, it’ll start to feel wrong when you write code that doesn’t have good documentation. You’ll start pointing out ways to improve documentation to your coworkers during code review. One little habit will improve your team’s code for your entire business.

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

About the author

Eric Boersma

Contributing Author

Eric?Boersma?is a software developer and development manager who's done everything from IT security in pharmaceuticals to writing intelligence software for the US government to building international development teams for non-profits. He loves to talk about the things he's learned along the way, and he enjoys listening to and learning from others as well.