Writing excellent code documentation is a skill that takes time and regular effort to maintain. There is, however, a lot to be gained by putting the effort in and making sure we have well-documented code.
We’re going to explain what we mean by code documentation, the outsized impact that documentation can have for your business, and round up by sharing some excellent examples.
What is Code Documentation?
Code documentation is text that accompanies software code to explain what your code is doing, why it’s written the way it is, and/or how to use it. There are two main categories of documentation: documentation inside the code and supporting documentation about the code.
Documentation in Code
This type of code documentation refers to notes left in the same file your code is in. When your code is running, these notes are ignored by your programming language but are used by both developers reading the code and some tools that can generate information based on the comments.
In Ruby, we might see the following as an example of a code comment.
# Adds two numbers together
def calculator(x, y)
x + y
If you need to comment to describe what your code is doing, it may be better to rewrite part of your code to make it more clear. In our example, if we changed the method to be called `add` then we probably don’t need the code comment.
However, sometimes making changes to make things more clear can take time or is difficult to accomplish. In those cases, it is better to have a comment than to have nothing.
Another reason to use documentation inside of your code is to leave instructions for third-party tools. For example, Rubocop is a popular tool used in many Ruby projects that can report on the quality of your code. Sometimes, for better or worse, we need to have code that would fail a Rubocop check. We can insert comments that are useful to both the people reading the code and to Rubocop, which is looking out for specially formatted comments like the example below.
# rubocop:disable Metrics/LineLength
# rubocop:enable Metrics/LineLength
These comments are useful to people reading because you can immediately know there are going to be some very long lines in this method, but they are presumably there for a good reason.
It is also useful to Rubocop. Rubocop knows that between those comments to not worry about reporting on the fact that there are very long lines.
Documentation About Code
These are supporting documents that don’t necessarily sit in the code, but are used to supplement people’s understanding of the code.
Several categories of documentation could fall into this category. The most common are:
A README is a high-level overview of what the project does and shares advice on how to run the project locally.
To get this project running on your local machine, please install:
Then run the following commands to get up and running…
Developer / API docs
Documentation aimed at developers to help explain in detail which parts of the code they can use and how they should use them. This type of documentation can be automatically generated from code comments.
Often the best way to describe something is with an example. This type of documentation consists of well-documented example code that people can run themselves to get an idea about how things work.
With our `add` method above, the example documentation could look like;
# require our file into your project
# use the add function to add two numbers together
answer = add(40, 2)
# answer will equal 42
The Impact of Great Code Documentation
There are many benefits to having your documentation in great shape. Three of the most significant advantages are: reduced development time for new features, fewer support requests from people using your code, and more people finding out about your business.
These benefits might sound surprising, but proper documentation reaches way further than your developers.
External contributors to your open source code benefit because they can quickly get up to speed with the features and what the code is meant to do.
Developers in other organizations who are looking to use new technologies can use your code examples and developer docs to evaluate usefulness.
Product owners doing preliminary research on a new feature can see the high-level features of your code from your developer docs. They may not understand the underlying functions, but they don’t need to. Well-written documentation will tell them what they need in plain language.
Reduced Development Time
Developers who can quickly get the context surrounding the code they are working on will be much more productive. Supplying excellent documentation not only helps people get up to speed quickly but, depending on their development setup, might also help their tooling to allow the developer to be more productive.
Some code editors can interpret comments and use them to share documentation in line as the developer is writing code. This means less time spent searching for information about what they can do with the code and more time writing it.
Fewer Support Requests
The more documentation you can provide, the more people will help themselves. This means they are less likely to contact support asking for help with particular aspects of your code.
Any code-related support questions you receive should be considered for addition into some part of your code documentation, as this will help more people in the long run.
More People Finding Out About Your Business
Having your documentation in the open means search engines like Google can index the pages and show them to people who are searching for solutions to particular problems. These are the types of issues that won’t sit nicely on your marketing pages, but searchers will be made more aware of your product.
This will not only get you more leads, but your leads will also be more qualified. They’ve already seen some of the technical features of your product and have opted to contact you.
Our Favorite Examples of Code Documentation
There are plenty of projects that get code documentation right.
Ruby on Rails
The Ruby on Rails project has nice in line documentation in their codebase. When you’re learning about which method to use, you can quickly view the source code and know the method is well documented.
One of the reasons Rails has been so widely adopted is how quickly people can learn it. The documentation has a large part to play in this rapid adoption.
The GoCardless service for handling recurring payments with Direct Debits has some fantastic docs that help explain how to get started, and include plenty of code samples that you can try yourself.
With so many examples covered in these docs, developers will rarely need to contact GoCardless’ support for clarification.
Stripe is a payments platform that has always claimed to be “Developer First.” The developer guide backs up that claim with clear examples and use cases.
Because of their large amounts of documentation, they are often the page you land on when searching for payment related development queries, which is going to win them business.
We have our own documentation for different projects, check out our README for the TextExpander Touch SDK.
Writing good documentation in and about your code will not only help you in the moment to better clarify your thinking, it will have a long-term positive impact that reaches far beyond your immediate team.
Which companies do a great job of code documentation? Let us know in the comments.