Automatic code formatting & Orange

The importance of code style

Code style may seem like a trifling issue, but the importance of it should not be underestimated. It may not seem like it at first, but the more the code base of a project grows, the more the number of projects grows and the more the number of people in the team grows, the more there is a need for consistency and readability.

Here at Quantlane, we have a few large projects and a lot of small projects. Not wasting time & energy adapting to a different code style just because you open a file in a project you haven't seen before is very important.

Personally, I've been in a few discussions about the best code style and I have had strong opinions about a few things (like a comma after the last list item so when you add an element, you don't get a noisy git diff) and didn't care about a few others. Over time, after spending hours on these debates, I've come to the conclusion that it's just not productive. Now I accept any code style as long as it is reasonably readable and as long as it is applied to the whole code base and preferably across all the projects in the team. It saves time not having these debates and it saves mental energy, because you don't have to adapt to anything new.

Code style must not stand in the way

As I've described above, having a code style in your team or even for your own project saves time & mental burdens. We can and we do go further than that. We use code formatters that save even more. You just write your code, and without breaking your train of thought, your code can get reformatted on file save, on a keyboard shortcut or any other preferred method. You don't have to break lines just because you add way too many arguments to a function and instead of one line for all, each should have its own now. Although it may not be much, it is one of the many small things we try to optimize. We try to avoid repeating tasks that have no value on their own. We value people's thought processes and time. One neat benefit of using a code formatter is not having to remember a code style.

Embracing the idea of using such tool may not actually be a mentally easy task, but once you sort of give up control over how your code looks, you get all the described benefits. Of course to make sure every project follows the agreed on code style, we use pre-commit hooks and CI checks to make sure the code that gets in our repositories complies with the code style.

Code formatters are pretty cool ... Are they also safe?

In our front-end projects, we use prettier. In our Python backend projects, we use Black, a popular opinionated PEP 8 compliant code formatter.

The way these modern tools work is that they compose an Abstract Syntax Tree (AST) of the source code and then build the reformatted source code from that parsed tree using the configured formatting rules. The original formatting therefore doesn't matter (well, small exceptions apply).

What Black does for extra safety by default is that it parses its own output into an AST and compares it with the AST of the original source code to make sure the code is indeed the same and saves the formatted output only when those two trees match. (Actually there are small intentional exceptions where Black considers two distinct tree nodes the same, but only when it has no change in the code functionality.)

Remember I said we use Black for our Python code? Well, it is mostly true. Read on!

Orange is the new Black

The most important thing about code formatters is that they make code consistent and you don't have to overly think about it. Often, they are opinionated so you don't choose much about the code style, intentionally. Usually, you can tweak a few things that are highly controversial or depend on your project. For Python projects, Black is a great choice.

When we started using code formatters, we had different opinions and therefore have forked Black, tweaking the original opinionated rules, keeping the awesome rest of the tool. If you're a fan of TV shows, you get the pun already. Orange, as our new Black, does a few things differently to the original project:

• indentation with tabs (let's not start a flame war now),
• single-quoted strings (more readable for us),
• default line length is 110 (also more readable)

and a few others that we find improve readability, such as expanding comprehensions into multiple lines if they don't fit in one comfortably:

# Black
long_list_of_comprehension = [
    pineapple for pineapple in self.pineapples if getattr(pineapple, "is_still_fresh", False)
]
short = [s for s in l if s]

# Orange
long_list_of_comprehension = [
    pineapple
    for pineapple in self.pineapples
    if getattr(pineapple, 'is_still_fresh', False)
]
short = [s for s in l if s]

The opinionated rules don't matter that much when they make the code readable ... so why not tweak them, when you start using a code formatter. 😉

orange is open-sourced under the MIT license and is tested to work with Python 3.7 to 3.9. It is available on PyPI with a simple pip install ql-orange and the source code is on our GitLab.

Conclusion

Here at Quantlane we love to learn and to solve interesting problems. Therefore we try not to waste time on things that get us nowhere. We love to focus on our tasks, to get into flow and not context-switch to things that we can easily eliminate. That's why, among other things, we use code formatters to make our lives easier and if you don't already, try it too. Seriously, give it a shot and let us know whether you reap the same benefits that we do. For feedback about Orange talk to us at 💌 code@quantlane.com.