Code documentation good practices

By Francisco Verastegui – Santex’ Technical Board Member

Code documentation is an important practice of the development process and it’s worth the effort in the long term as the application gets bigger and more complex, letting us save time and minimize the learning curve to understand the functionality of the API, libraries and applications. Here we explain 4 practices that we hope you embrace as part of your development process.

  1. Document your APIs in a simple and concise way

Libraries and APIs are made to be used by people that might not have time to read the code or just might not have access to it, so documentation should reflect your code objectives in a simple (easy to understand) and concise (focusing on the important facts) way.

  1. Keep your documentation code up-to-date

Update your documentation each time you change your code – especially if business rules are affected. Software evolves over time, and so does the code. Therefore it’s important not to start documenting too early in the stages of the code because you might be forced to change it a lot of times.

  1. Focus on the ‘Why’ not the ‘How’

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

Good source code can be self-explanatory, but we should give it meaning. So we shouldn’t repeat the how. The following examples explain the same method with different code documentation approaches. The examples are in Java, but we are able to apply these concepts to any other programming language as well.

Example 1

In this case, the code documentation (JavaDoc) just explains the ‘How.’ The context isn’t clear, and neither are the business rules that are the reason of the creation of the method. Basically, the documentation is providing the same information that we could get reading the code.

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 and 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 to 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: Explanation of the reason (Why) the method is throwing a specific type of exception. It is recommended to do this 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.

  1. Don’t document trivial code

Avoid documenting getter or setter method (unless it does something business-related), so remove it from your IDE’s auto-generated code template. Avoid documenting simple procedures perfectly explained in reading the code. For example:

As you can, see doing this only makes code harder to read.

Leave a reply