Best Practices for Code Documentation

by

Many developers dislike writing technical documentation and they waste a lot of time while doing it. Code documentation might be required by management, but often developers see it as a chore that adds no value to their project. Even worse, a wrong approach to code documentation can lead them to write misleading or even incorrect comments.

Code is one of the most important parts of any integrated circuit, and therefore it is critical that it is well-documented and in a standard format. The Best Practices for Code Documentation program at El Camino College helps students learn how to use code documentation tools and what the best practices are for keeping their code clear and understandable.

Whether you’re a seasoned programmer or are taking your first steps into coding, it’s essential to learn how to document your code. But why should you do so, and what’s the best way to do it? Why is code documentation important? There are many benefits of documenting your code. Firstly, if you’re working in groups with other developers, documenting your code makes it much easier for everyone to understand each other’s progress and build on top of one another’s work. Secondly, when you revisit a project after a period away from it, whether that be a week or a whole year, it can be really hard to remember what your specific logic was or what every function achieved – this can involve going through old code manually and trying different things out until you get back up to speed.

Code documentation is helpful for these times and allows us to quickly jump back in without too much hassle! It also lets other people quickly start learning new systems without going through all the pain we did when creating them. So now we know why it’s important – but what is the best way of doing so? Code documentation tools help structure documentation so that it is consistent between authors and readable by both humans and computers.

Why do you need code documentation?

Despite a common misbelief, code documentation is used to describe not “WHAT the code does?”, but “HOW it does it?” Its main purpose is to increase the product’s maintainability, regardless of who might be working with the code.

There are several reasons why code documentation is crucial for any project.

  • It is good for knowledge transfer. Not all code is equally obvious. There might be some complex algorithms or custom workarounds that are not clear enough for other developers.
  • It helps to troubleshoot production issues. If there are any problems with the product after it’s released, having proper documentation can speed up the resolution time. Finding out product details and architecture specifics is a time-consuming task, which results in the waste of your money.
  • It may help you better manage any additional integrations and product add-ons. Product documentation describes dependencies between system modules and third-party tools. Thus, it may be needed for integration purposes.

All in all, having your application properly documented will make the development and maintenance efforts more efficient and will save you time and money in the long run.

Remember, that poor code documentation or its complete lack thereof, is one of the signs that your vendor might be dishonest. They might use this down the road to leverage their position over you and prevent you from switching providers. If the code is properly documented, your current development team can be easily replaced. If it is not, you are trapped.

So, why is technical documentation so important?

Good documentation explains not only what the code does, but also how it does it. Without documentation:

  • It will be more difficult for someone else to pick up your code and work on it later. Plus onboarding new team members becomes a laborious process. Fixing bugs without any context/documentation; just not ideal.
  • It will be difficult (though probably not impossible) for you to pick up your code and work on it later. Think about how many projects you will have worked on and how much code you will have written 3 or 6 or 12 months down the road. How could you possibly remember what you were thinking when you wrote the code you finished today?

What does good documentation consist of?

Having no documents at all is as bad as having excessive or inappropriate documentation. Here are some basic rules for creating useful and, most importantly, usable code documentation.

  1. Keep it simple and concise. Follow the DRY (Don’t Repeat Yourself) principle. You don’t need to comment on every single line of your code, use comments to explain something that really needs explaining and is not self-evident.
  2. Keep it up to date at all times. It’s best to document the code step by step, as it is written, instead of writing down the comments for the code that was written months ago. In doing so, you will save time and make the documentation precise and complete. Use proper versioning to keep track of all changes in the document.
  3. Document any changes to your code. Documenting new features or add-ons is pretty obvious. However, you should also document deprecated features, capturing any change in the product.
  4. Use simple language and proper formatting. Code documents are typically written in English so that any developer could read the comments, regardless of their native language. The best practices for documentation writing require using the Imperative mood, Present tenses, preferably active voice, and second person. Use consistent header, footer, headings, and font sizes for better readability.
  5. Combine automated documentation tools and human input. Automation will speed up the process, but a person can make the code documentation comprehensible while adding more of a personal touch.

As for the latter, there are plenty of tools that will do the hard work for you (documenting the code). Such tools are typically language-specific:

Slate and Swagger are among the most popular tools for API documentation.

Documentation Best Practices

“Say what you mean, simply and directly.” – [Brian Kernighan] (https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)

Contents:

  1. Minimum viable documentation
  2. Update docs with code
  3. Delete dead documentation
  4. Documentation is the story of your code

Minimum viable documentation

A small set of fresh and accurate docs are better than a sprawling, loose assembly of “documentation” in various states of disrepair.

Write short and useful documents. Cut out everything unnecessary, while also making a habit of continually massaging and improving every doc to suit your changing needs. Docs work best when they are alive but frequently trimmed, like a bonsai tree.

This guide encourages engineers to take ownership of their docs and keep them up to date with the same zeal we keep our tests in good order. Strive for this.

  • Identify what you really need: release docs, API docs, testing guidelines.
  • Delete cruft frequently and in small batches.

Update docs with code

Change your documentation in the same CL as the code change. This keeps your docs fresh, and is also a good place to explain to your reviewer what you’re doing.

A good reviewer can at least insist that docstrings, header files, README.md files, and any other docs get updated alongside the CL.

Delete dead documentation

Dead docs are bad. They misinform, they slow down, they incite despair in engineers and laziness in team leads. They set a precedent for leaving behind messes in a code base. If your home is clean, most guests will be clean without being asked.

Just like any big cleaning project, it’s easy to be overwhelmed. If your docs are in bad shape:

  • Take it slow, doc health is a gradual accumulation.
  • First delete what you’re certain is wrong, ignore what’s unclear.
  • Get your whole team involved. Devote time to quickly scan every doc and make a simple decision: Keep or delete?
  • Default to delete or leave behind if migrating. Stragglers can always be recovered.
  • Iterate.

Prefer the good over the perfect

Your documentation should be as good as possible within a reasonable time frame. The standards for a documentation review are different from the standards for code reviews. Reviewers can and should ask for improvements, but in general, the author should always be able to invoke the “Good Over Perfect Rule”. It’s preferable to allow authors to quickly submit changes that improve the document, instead of forcing rounds of review until it’s “perfect”. Docs are never perfect, and tend to gradually improve as the team learns what they really need to write down.

Documentation is the story of your code

Writing excellent code doesn’t end when your code compiles or even if your test coverage reaches 100%. It’s easy to write something a computer understands, it’s much harder to write something both a human and a computer understand. Your mission as a Code Health-conscious engineer is to write for humans first, computers second. Documentation is an important part of this skill.

There’s a spectrum of engineering documentation that ranges from terse comments to detailed prose:

  1. Inline comments: The primary purpose of inline comments is to provide information that the code itself cannot contain, such as why the code is there.
  2. Method and class comments:
    • Method API documentation: The header / Javadoc / docstring comments that say what methods do and how to use them. This documentation is the contract of how your code must behave. The intended audience is future programmers who will use and modify your code.It is often reasonable to say that any behavior documented here should have a test verifying it. This documentation details what arguments the method takes, what it returns, any “gotchas” or restrictions, and what exceptions it can throw or errors it can return. It does not usually explain why code behaves a particular way unless that’s relevant to a developer’s understanding of how to use the method. “Why” explanations are for inline comments. Think in practical terms when writing method documentation: “This is a hammer. You use it to pound nails.”
    • Class / Module API documentation: The header / Javadoc / docstring comments for a class or a whole file. This documentation gives a brief overview of what the class / file does and often gives a few short examples of how you might use the class / file.Examples are particularly relevant when there’s several distinct ways to use the class (some advanced, some simple). Always list the simplest use case first.
  3. README.md: A good README.md orients the new user to the directory and points to more detailed explanation and user guides:
    • What is this directory intended to hold?
    • Which files should the developer look at first? Are some files an API?
    • Who maintains this directory and where I can learn more?

Code documentation is an important part of the development process. Understanding code documentation is worth the effort in the long term, especially as applications get bigger and more complex. Code documentation allows us to save time and minimize the learning curve in understanding the functionality of the API, libraries and applications. 

Conclusion

As programming languages and platforms advance faster than ever, there is an inexplicable need for programmers to document their source code. Even if the source code is well-commented, it may be difficult to understand. When writing code, it’s important to document your work as you go. Rather than waiting until after you’ve written the entire program. Having a process in place that allows you to write documentation as you create your code can provide a number of benefits, including smoothing out the development process and saving time as you go.

There are a lot of great open source projects out there. One practice that helps to improve these projects is integrating the documentation into the source code and making sure it’s up to date.

Leave a Comment