Welcome to the series "Clean Code"; brought to you by "Coding Mantis"!

It seems that there's a debate between two schools of programmers; those who believe we should add comments on our code and those who believe otherwise.

The first school (Team A) supports that code should be thoroughly documented in order to describe its functionality. The other school (Team B) would argue that good code is self-explanatory and the need to document it suggests that it's not optimally written.

So, who's right?

I believe the answer to this question, as with most things in life, lies in the gray area in-between.

From my personal perspective, it really depends on what you aim to do and which setting you're in.

Point for Team A

If you're developing a library, have in mind that usually your code will either be treated as a black box or people will take a quick swim around the surface and then go on about their jobs. This is where documentation comes into play and depending on the language you're using you may come across terms such as JavaDocs, JSDocs, etc.

What are these "Docs" you're writing about?

To put it simply; they're a way to let other people, that will be using your code, know what it does and how it does it by providing a description, its input, its output, whether or not it throws an exception, and optimally some example scenarios. This way we're able to take a quick look at it without even having to delve deeper into the code itself.

Point for Team B

To paraphrase some bits from the book "Clean Code" by Robert C. Martin (more on that great book coming in a later post), if we simply stick to giving meaningful names to our classes, methods, and variables and divide our code into small parts that have one and only one responsibility then our code will be self-explanatory and no documentation will be required.

Can we take a look at an example?

Glad you asked; I'll demonstrate a short and simple example as we will take a deeper look into clean code later on.

Let's assume the following snippet lives happily in your codebase.

public class Customer {

    private Set<String> addresses;

    /**
     * Adds an address to the customer's set of addresses.
     * Each unique address can exist only once.
     * If the set is null, it instantiates a new HashSet 
     * and adds the address to it.
     * 
     * @param address - the address to add
     */
    public void addAddress(final String address) {
        if (null == this.addresses) {
            this.addresses = new HashSet<>();
        }

        this.addresses.add(address);
    }
}

Examining it from Team A's perspective we would say that the code is documented well enough to provide clarity as to what our method does and how it behaves.

Examining it from Team B's perspective we would say that the code is cleanly written, thus there's no need for the provided documentation, as someone can immediately notice its behaviour just by looking at it.

At this point, both teams would be correct but there's a key difference, I believe, that could steer our opinion towards one or the other — hint; context.

If our codebase is a library, then for me the documentation is well placed; remember what I said previously about it being treated as a black box?

If it's not, however, a quick, maybe quicker look into the code would let us know the exact same thing, thus deeming the documentation redundant.

What do you think about the subject?