Clean Code — Comments

3 min readJun 23, 2022

This post is part of the Clean Code Series, if you haven’t read the first one regarding the importance of naming, you should check it before continuing.

This article is about the importance of comments when we’re writing code.

We usually think that comments help with code readability, but can be quite the opposite case though.

Bad Comments

There are a lot of bad comments which can be added to the code. In the best case, “bad” means “redundant” and in the worst case, it means “confusing” or even “misleading”.

Makers & Dividers

Dividers and markers are redundant. If our code is written in a clean way (we’re using proper names etc.), it’s obvious what our different code parts are about.

We don’t need extra markers for that, they only stop the reading flow and make analyzing the code file difficult.

public class User {
    /*
     *** Variables ***
     */
    
    String firstName;
    String lastName;
    Date birthDate;    /*
     *** Constructor ***
     */
    public User (){ }
}

Redundant Information

public User createUser(){ // creating a new user
        return new User();
    }

This type of comment adds nothing. Instead, we stop and spend time reading them, just to learn what we already knew because the code used proper names.

The following could be useful if we had poor naming:

public User build(){ // creating a new user
        return new User();
    }

But we should avoid poor names in the first place.

Commented Out Code

We all do that from time to time.

public User createUser(){
        return new User();
    }//    public void deleteUser(){
//        ...
//    }

But we should try to avoid commenting code. Just delete it instead!

We can always use the source control (Git) and bring back the old code if we need it. The commented-out code just clutters our code file and it’s harder to read.

Misleading Comments

The comments that mislead the reader are the worst kind of comments.

public void login(){ //creating a user
        ...
    }

In the above example, the function name indicates a login action, but the comment implies that it creates a new user…? — We don’t know, and more than that now we have to analyze the complete function (and any other functions it might call) to find out.

Definitely avoid these kinds of comments.

Good Comments

There are a couple of comments which could make sense, let’s go through them.

Legal Information

In some projects and/or companies, we could be required to add legal information to your code files.

// (c) Company Name

Usually, the comment is right at the top of the file and it’s not a big issue. And of course, there is nothing wrong with these kinds of comments.

“Required” Explanations

In rare cases, adding extra explanations next to our code does help, even if we named everything properly.

// Min. 8 characters, at least: one letter, one number, one special character
    String passwordRegex = "/^(?=.*[A-Za-z])(?=.*\d)(?=.*[@$!%*#?&])[A-Za-z\d@$!%*#?&]{8,}$/";

The name passwordRegex tells us that this regular expression will be used to validate passwords, but it's not immediately clear. Regular expressions are not that easy to read, hence adding that extra comment doesn't hurt.

Warnings

Also in rare cases, warnings next to some code could be useful, for example, if a unit test may take a long time to complete or if a certain functionality won’t work in certain environments.

TODO Notes

Even though, we shouldn’t overdo it, adding “TODO” notes can also be fine.

public void deleteUser(){
        //TODO: ...
    }

Would be better to implement a feature completely or not at all — or in incremental steps which don’t require TODO comments. But leaving a TODO comment here and there won’t hurt, especially since modern IDEs help us find these comments.

Obviously, it will not help readability if we have a bunch of TODOs everywhere.

Hope this will be helpful in your journey as a Java programmer and keep up the good code!

And don’t forget to check my new blog JavaCodeBox.