Watch your Coding Manners

If I were to recommend just 1 book to read to anyone that wants to improve their code quality, I wouldn't even think it twice to choose:

I'm not a book addict by any means, heck, I still haven't finished many books I was assigned to read while I was in school!

(Sorry mom, but you probably didn't do it either).

But with Clean Code I took it really slow and even jumped from one chapter to another just by selecting the titles that catched my attention. This is probably the #1 reason why I didn't drop it.

Of course, there are parts of it that I still don't quite understand 100%, but the overall reading experience was really pleasant.

One of my favorites quotes from the author is:

Whenever a coworker/friend asks me for help with a piece of code, the first thing I notice is their code structure, how "good" does it look from far away.

There are many things that can be noticed from a few feet away:

• Curly braces position.
• Line length and breaks.
• Indentation levels.
• Bad Comments.
• Number of parameters.

Our eyes can detect all these details because of the Gestalt Grouping Principles

Now, I would like you to follow me while we repeat each item with an increased font size:

Curly braces position

Depending on your background, you may be used to doing either

// C#, C++, C...

public void CoolFunction()
{
    // Something cool
}

Or

// Java, Kotlin, JavaScript...

public void anotherCoolFunction() {
    // Something even cooler
}

And whenever I bring this up, the usual response is

"I'm just more used to X style, Chris!" - Imaginary person

Yeah, I get it. But I don't think this is valid reason/excuse. Whenever your code gets pushed to master it is no longer yours. It belongs to the team.

So, we will have to sacrifice our habits for the greater good:

A codebase should look like it was written by only one person.

Line length and breaks

Line length

There's a general rule of thump that says that each line shouldn't be longer than ~80 characters. Which brings us to...

Line breaks

You may have seen code that looks like this:

// Java

SomeBuilder builder = new SomeBuilder();
builder.doThis().doThat().andAlsoThis().butDontForgetThis().build();

This can easily get to pass the 80 characters length, so in order to improve readability we can use line breaks:

// Java

SomeBuilder builder = new SomeBuilder();
builder
    .doThis()
    .doThat()
    .andAlsoThis()
    .butDontForgetThis()
    .build();

Yes, it will make your code have a few extra lines overall, but your eyes will thank you later. Now we can read each statement like if it were a list.

Indentation levels

This is probably one of the most common scenario.

Let's say you have to verify some conditions before you do something, like:

// Java

Girl girl = new Girl("Carly Rae Jepsen");
if (girl.isPretty()) {
    if (girl.isTheFlashFan()) {
        if (girl.isGeek()) {
            if (girl.isGamer()) {
                callMeMaybe();
            }
        }
    }
}

I may or may not be listening to Call Me Maybe right now...

We can change this by making a boolean variable that will hold an expression that can replace all the ifs:

// Java

Girl girl = new Girl("Carly Rae Jepsen");
boolean isTheChosenOne = girl.isPretty() && girl.isTheFlashFan() 
                         && girl.isGeek() && girl.isGamer();
if (isTheChosenOne) {
    callMeMaybe();
}

Not only are we able to make our code more expressive, but also minimize the mental load of the readers of our code with this type of changes.

Bad Comments

Wait!

Before you go down to the comments section and blast me with your infinite wisdom, you gotta admit that there are some comments that are just bad.

// Java

// Returns name
public String getName() {
        return name;
}

The method already expresses what it does (specially when you can see it is a Getter method just by it's name).

Getter methods usually follow the get<Something> naming convention.

Good comments should say why something was made that way or at least be informative, rather than saying what the code does. If you can remember that, your commenting game will be 🔥.

// Java

public void complicatedAlgorithm() {
    // This is our best attempt to solve ticket #12345,
    // for more information, please refer to www.somedomain.com/something

    // ...
}

Number of parameters

If you find yourself writing functions/methods/constructors with 2-3 or even more parameters, there's a high chance that you may be able to abstract away some of them with a class that can represent them even better.

// Java

public void moveTo(double x, double y) {
    // ...
}

We can extract a class out of these 2 parameters and call it Point.

// Java

public class Point {
    private double axisX;
    private double axisY;

    public Point(double axisX, double axisY) {
        this.axisX = axisX;
        this.axisY = axisY;
    }

    public double getAxisX() {
        return axisX;
    }

    public double getAxisY() {
        return axisY;
    }
}

Then we can refactor our moveTo() method to this:

// Java

public void moveTo(Point point) {
    // ...
}

And we just scratched the surface, there are plenty of more ways to improve your codebase. But this is the part where I encourage you to read Clean Code to find out by yourself 🤓.