Horizontal and Vertical Code Formatting

Code Formatting

Each programming language has its own standards for code formatting. You always want to format your code with the programming language's standard first. What is discussed in this article can be applied across most programming languages.

Code readability comes from how the code is written as well as how the code is formatted. You can have well-written simple code but have poor formatting, making it difficult to read. Well-formatted code can help your eyes scan the code and go directly to the source of what you are looking at.

Another thing to consider is how many times your code is indented. Code that isn't indented more than three times will naturally follow good coding practices.

Horizontal Formatting

The first thing to consider with horizontal formatting is the maximum length of a line of code. Generally, this is between 80 and 120 characters per line. This keeps horizontal code short and consistent. When you do have a line of code that is too long, what do you do? The following example is less than the max length above but is being used just to show this principle.

// Java code
cleanUpAllAdminUsersThatHaveBeenExpiredSince(usersToExclude, 
        startingTimestamp, endingTimestamp);

This type of formatting is common to see when a line gets too long. This does not read well. The mindset is the line is too long, so put it on multiple lines. That is usually where the thought process stops.

If you were to write a grocery list, would you write it like this?

Eggs, coke, wheat bread, apples, bananas, oranges, carrots, 
noodles, honey, bacon, rice, milk, potatoes...

Or are you going to write it as a list like the following?

eggs
coke
wheat bread
apples
bananas
oranges
carrots
noodles
honey
bacon
rice
milk
potatoes
...

Don't format code like sentences in a paragraph.

Vertical Formatting

Vertical formatting is more of thinking of your code as lists. When you have a long line or more than two parameters in a method, format the code vertically like the following:

// Java code
cleanUpAllAdminUsersThatHaveBeenExpiredSince(
    usersToExclude, 
    startingTimestamp, 
    endingTimestamp
);

You will notice in this example the ending parentheses and semicolon are on their own line. This makes it more readable by moving the method arguments into an indented list of arguments.

Formatting code this way will make it more readable when looking at code changes through source control. It will also reduce the changes in some cases, and you will be able to see only what code was changed.

Consistent Formatting

Stick to formatting that is consistent. For example, the following method has the method parameters formatted vertically as a list.

// Java code
public void write(final String path,
                  final String name,
                  final byte[] contents) {

    // ...
}

This code is formatted nicely and is easy to read, but the formatting won't be consistent. The indentation will change depending on the length of the method signature. Version control can show the first line as changed if the method signature or the first method parameter changes, two concepts on the same line. The better way would be to introduce the parameters on a new line. This keeps the formatting consistent no matter what the method name is.

// Java code
public void write(
        final String path,
        final String name,
        final byte[] contents) {

    // ...
}

This formatting allows your eyes to scan the method signature easily.

This same formatting should be done when creating objects or collections.

// Java code
final var users = Arrays.asList(
    admin,
    current,
    new User(
        "user-name",
        "user-id",
        "thumbnail"
    )
);

Conclusion

Horizontal code is great for short lines. When lines become larger, stick to vertically formatted code. This makes the code easier to read. It will also make the code easier to read when looking at changes through source control.