Authors: Chua Ka Yi Ong
Software documentation refers to information that explains the code in a software project or how to use a software product or API. Many developers neglect writing documentation because they find it boring or troublesome, which is a pity because documentation communicates what you have done to the world - without documentation, people won't know about your awesome code or cool features.
The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it’s not whether they prefer Python or Java. It’s whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless. By writing clear technical documentation for end users, they allow people to figure out what their code is supposed to do, which is the only way those users can see the value in their code. There’s a lot of wonderful, useful code buried on sourceforge somewhere that nobody uses because it was created by programmers who don’t write very well (or don’t write at all), and so nobody knows what they’ve done and their brilliant code languishes.
Advice for Computer Science College Students, by Joel Spolsky
There are many benefits to writing good documentation, such as the following:
Documentation should not be written for the sake of writing, but rather, to fulfill a need. Good documentation is up-to-date and includes only what is necessary.
Documentation comes in many different forms. Below are some guidelines on how to tackle each type of documentation.
Written documentation refers to what people usually think of as documentation - READMEs, user guides and developer guides.
In general, written documentation should use:
Futhermore, you should always:
This provides useful general tips for writing documentation and this guide provides more tips on writing well.
A README serves as an introduction to your project, and is often the first thing people see when encountering your project.
A good README should convince users to use your product or contribute to your code, by providing enough information to make it easy for them to get started.
For a good guide on how to write a README, check out this guide.
A user guide teaches users how to use your software. User guides can include quickstart guides, reference materials, tutorials, cookbooks/recipes and more.
Here is a useful guide on how to tackle different types of user documentation. This points out the problems with common approaches to documentation and builds on the previous article.
Developer guides teach new developers how to contribute to the code base. They should give an overview of the code and an explanation of the design, as well as include instructions for setting up, making changes and deploying.
See this to learn more about what to include in a developer guide.
Code docummentation refers to documentation that is found within the source code. All the following types of code documentation are important and complement one another. Note that such documentation should always be updated together with the code.
Comments are a well-known form of documentation. They complement the code and are intended for developers who use and work on the code. They include API documentation for variables, methods, classes, and packages, as well as inline comments.
API documentation for variables, methods, classes, and packages explain what they do. Good API documentation should enable users to use the API without having to guess how to use it or be confronted with unexpected behavior. Thus, comments for methods should include the input and output, assumptions, edge cases and possible exceptions or errors thrown by the method.
Comments can also refer to inline comments. Even the most well-written code can leave ambiguous questions. For example, code cannot explain why a line of code was written in a specific way, as discussed in this article. In such cases, well-written comments can clarify and make the code easier to understand.
Note however, that excessive comments are also a code smell. Comments should not repeat what the code is saying and requiring a lot of comments to explain what you are doing can suggest that the code is too convoluted. Often, comments can be replaced by clearer code. As much as possible, code should be written as clearly as possible, with comments added in only when necessary. This Stack Overflow answer gives a good example on how to do this. For a more detailed explanation, read this article.
The source code is a form of documentation. Well-written code makes it easy for developers to understand what the code is doing. This can be done via a number of ways, such as
Tests are another form of documentation as they make the expected behavior of the methods clear for different types of input and edge cases.
Version control is also a form of documentation. Having access to how the code base was changed over time can shows how, when and why a piece of code was written or changed. For this to work well, it is important to write good commit messages and follow good commit practices.
This explains what to include in commit messages while this article explains how to use Git to make full use of your code's version control history. For more resources on commit messages, check out this Stack Overflow thread.
In addition to the links mentioned above, here are the links used in the writing of this article: