Best Practices in Code Documentation

By Francisco Verastegui – Santex Technical Board Member

Code documentation good practices

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. Here we explain four practices that will help you embrace code documentation as part of your development process.

Document your APIs in a simple and concise way

Libraries and APIs are designed to be used by people who might not have time to read code or may not have access to it. Because of this, documentation should reflect your code objectives in a simple (easy to understand) and concise (focusing on the important facts) way.

Keep your code documentation code up-to-date

Whenever you change code, the code documentation should be updated. This is especially true if business rules will be affected. Software evolves over time, as does the code attached to that software. Therefore, it’s important not to start the code documentation process too early since you may need to make a lot of changes.

Focus on the ‘Why,’ not the ‘How’

Code documentation should explain ‘Why’ and the code ‘How’. The main idea of this principle is: “Your code documentation should explain the “why” and your code should explain the “how.””

Good source code can be self-explanatory, but we still need to give it meaning. This means not repeating the “how.” The following examples explain the same method with different approaches to code documentation. The examples are in Java, but we are able to apply these concepts to other programming languages, as well.

Example 1

In this case, the code documentation (JavaDoc) explains the “how.” The context isn’t clear, nor are the business rules that are the reason for the creation of the method. Basically, the code documentation is providing the same information we could get by reading the code.

Not clear code documentation

Example 2

In this example, the method’s JavaDoc focuses on the “why,” explaining the context and the business rules that support it. It is also important to explain the business reason behind an exception that the method might throw.

Detailed Explanation

“When we are editing a recurring series:” This is the context. Whether to include it or not will depend on if it is a business-related method or just an ‘isolated’ method like the ones we can find in a utility class (reused by different parts of our code).

“We have to enforce the rule that recurring {@link Order}s can’t exceed a period of more than 24 hours:” This is the main part providing the “why” because it explains a business rule. It also explains the main reason for creating the method. A method can explain, or be supported by, more than one business rule.

“If the remove TIME portion is less than the install TIME portion, then it is safe to assume that the remove date has rolled onto the next day (e.g. June 1st 7PM -TO- June 2nd 3AM, is still a 24 hour period):” Business rule considerations are important so that we can have a good understanding of the method behavior. To include it or not will depend on the complexity and conditions of the rule we are trying to code.

@throws OrderEditException

– if the order was already deleted by a different user: There needs to be an explanation of the reason (Why) the method is throwing a specific type of exception. Doing this is recommended for any application business exception.

It is important to realize that it is perfectly possible to understand the meaning and the business implications of the method just by reading the code documentation. This is a key concept for APIs that are public and designed to be reused throughout different projects and applications.

Don’t document trivial code

Avoid documenting getter or setter method (unless it does something business-related). In order to avoid this, remove it from your IDE’s auto-generated code template. Avoid documenting simple procedures that are perfectly explained by reading the code.

For example:

Trivial code documentation example