Clean Code — Formatting

This post is part of the Clean Code Series, if you haven’t read the previous ones regarding the importance of naming and comments you should check them.

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

Vertical Formatting

Vertical formatting is about using the vertical space in your code file. It’s about adding blank lines and grouping related concepts together and adding space between them.

Adding Blank Lines

public void login(String email,String password){
        if(email.contains("@") || password.length() < 7){
            throw new Error("Invalid input");
        }
        User user = findUserByEmail(email);
        boolean passwordIsValid = compareEncryptedPassword(user.getPassword(), password);
        if(passwordIsVald){
            createSession();
        } else{
            throw new Error("Invalid credentials!");
        }
    }
    public void signup(String email, String password){
        if(email.contains("@") || password.length() < 7){
            throw new Error("Invalid input");
        }
        User user = new User(email, password);
        user.saveToDatabase();
    }

The code uses good names and is not overly long — still it can be challenging to digest. Compare with this code snippet:

public void login(String email,String password){
        if(email.contains("@") || password.length() < 7){
            throw new Error("Invalid input");
        }
        
        User user = findUserByEmail(email);
        
        boolean passwordIsValid = compareEncryptedPassword(user.getPassword(), password);
        
        if(passwordIsVald){
            createSession();
        } else{
            throw new Error("Invalid credentials!");
        }
    }
    
    public void signup(String email, String password){
        if(email.contains("@") || password.length() < 7){
            throw new Error("Invalid input");
        }
        
        User user = new User(email, password);
        user.saveToDatabase();
    }

It’s the exact same code but the extra blank lines help with readability. Hence we should add vertical spacing to make our code cleaner.

Vertical Density & Vertical Distance

Vertical density means that related concepts should be kept close together.

Vertical Distance means that concepts that are not closely related should be separated.

This affects individual statements inside a function and functions/methods as a whole.

public void signup(String email, String password){
        if(email.contains("@") || password.length() < 7){
            throw new Error("Invalid input");
        }
        User user = new User(email, password);
        user.saveToDatabase();
    }

In this example, there are two main concepts in this function: validation and creating a new user in the database. These concepts should be separated by a blank line.
On the other hand, creating the user object and then calling saveToDatabase() on it belong closely together, hence no blank like should be added in between.

If we had multiple functions, then functions that call other functions should be kept close together — with blank lines in between but not on different ends of the file.

If functions are not directly working together (not directly calling each other) it is ok if there is more space (other functions) in between.

Ordering Functions & Methods

When it comes to ordering functions, a good practice is to follow the “step-down rule”. A function A which is called by function B should be (closely) below function B — at least if the programming language allows such an ordering

public void login (String email,String password){
        validate(email, password);
    }
    
    public void validate(String email, String password){...}

Splitting Code Across Files

If the file gets bigger and/or if there are a lot of different “things” in one file (multiple class definitions), it is considered good practice to split that code across multiple files and then use import and export statements to connect the code. This ensures that the files as a whole stay readable.

Horizontal Formatting

Horizontal formatting is about using the horizontal space in the file — that primarily means that lines should be kept short and readable.

Breaking Lines Into Multiple Lines

Now, we can fit extremely long lines onto our screen — at least if we can read small text/fonts. But just because it fits into a line technically, doesn’t mean that it’s good code.

Good code should use relatively short lines and we should consider splitting code across multiple lines if becomes too long.

User loggedInUser = email && password ? login(email, password) : login(getValidatedEmail(), getValidatedPassword());

This is too long and too much code in one line.

The following snipper holds the same logic but is easier to read:

if(!email && !password){
            email = getValidatedEmail();
            password = getValidatedPassword();
        }
        
        User loggedInUser = login(email, password);

Using Short Names

Names should be descriptive, but we shouldn’t waste space and make them harder to read by being too specific. Consider this name:

String loggedInUserAuthenticatedByEmailAndPassword = "..."

This is way too much! loggedInUser would be enough.

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.