Where To Write Documentation

I can use Word file, a private Wiki or write the documentation into comments inside the code base. Which one is the best? What are the advantages and disadvantages of each documentation?

In this post, I explain 3 types of documentation, with their advantages and disadvantages.

External Documentation

I had projects where the documentation was in external files, in Word files. Other projects where the documentation was in a private Wiki.

Having the documentation in several Word files (or other binary files) is one of the worst situation. As I can’t search through all the files. It’s hard to categorize the files (by features or by date or by system design). And sometimes a file should be in many folders.

Having a Wiki is easier. It allows me to perform a search over all the content. And I can add labels or tags if a description belongs to many categories.

But the worst part of both solutions is that the documentation is far away from the code. The documentation is useful if it’s up to date. But when I’m writing the code, I have to remember to update the documentation. That’s a lot of effort.

The only good advantage for these types of documentations is for the images. I can use images to describe high level of the application. But again, when I update an important feature of my application, I need to remember to update the image.

Document the Classes and Methods

/**
 * Makes the sum of two integers.
 * @param first: first integer
 * @param second: second integer
 * @return the sum of the two integers
 */
public int sum(int first, int second) {
    return first + second;
}

With Java, I have the Javadoc which allows me to explain the behavior of the methods or classes, with the input parameters and the returned value. But in the previous example, the Javadoc took me more time to write than the code itself.

This time, the documentation is very close to the code. I can consider the documentation inside the code.

But what happens if I modify the method to accept a list of integers? For sure I will forget to update the Javadoc.

The worst part of this documentation is that I can’t add images to describe the behavior. And the documentation is attached to low-level parts which evolves much frequently.

Document Inside the Code

What about putting the documentation inside the code?

public int calculatePercentile(List<Integer> values, double percentile) {
    // Check if the list is empty
    if (values == null || values.isEmpty()) {
        throw new IllegalArgumentException("The list of values cannot be null or empty.");
    }

    // Sort the list of values
    Collections.sort(values);

    // Calculate the index for the given percentile
    int index = (int) Math.ceil(percentile / 100.0 * values.size()) - 1;

    // Return the value at the calculated index
    return values.get(index);
}

This time the documentation is attached to the line of code. I can’t miss it when I edit my code. This means that this documentation will mostly always be up to date.

The disadvantage here, is that I can only describe very low-level code. I can’t export this documentation for product owners or for the clients.

Conclusion

Each documentation has its purpose, their advantages and disadvantages. Let list them into a table.

Sooner or later, the documentation will be outdated. The furthest the documentation is from the code, the sooner it will be outdated.

In fact, the code must be documented by itself. The name of the variables, the methods and the classes must be descriptive. Having a clear named, it’s easier to know what’s the purpose.

What about sharing documentation between two development teams, like the frontend and the backend team? I like to use Swagger. It allows to describe the behavior of each endpoint. But it must be configure in such a way that it updates with the code, not from an external file.