You should write boring code

I'm not an expert with tens of years of experience writing production-quality code, but I've been part of a team developing multiple projects. During that time, I've noticed some common misconceptions that more inexperienced developers have.

I wanted to share the most common misconceptions I found. To do that, let's take a look at an example from a project I did recently:

FILTER_KEYWORDS = ("sandbox", "mongo", "postgres", "memcached")
data = [
    line.split() for line in stdout.decode('utf-8').split('\n') if line
][1:]
data = [
    item for item in data
        if any([1 for keyword in FILTER_KEYWORDS if keyword in item[0]])
]

Did you understand what this code does? If you did, how long did it take you?

Let's see if we can make it better.

Make your code readable

I've mentored quite a few interns and this is a very common mistake that first catches my eye.

Let's start with a quote by Robert C. Martin (a super-important dude from the DEV world):

Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code.

Just think of the poor soul that needs to read your function in a month or so, while probably trying to find a crazy bug that intertwines with 5 other functions just like yours.

So, because of them - stop writing smart, elaborate code that only you can understand. Instead, try to make your code simple and easy to understand. This is part of what makes a great developer.

I am also susceptible to this mistake, but it's a good thing that my workplace has a code review culture that discourages this kind of coding. Also, ask yourself this:

• Would a less skilled developer understand how this code works?
• Would a less informed developer understand what this code does?

Keep things simple and always try to have someone to keep you in check.

Keep your code predictable

Code you write should always look the same. That means having the same naming conventions, indentations, whitespaces usage, etc. Python, for example, has its own style guide called PEP8 which I find to be a really good start.

Naming is especially important. It's really important to give a good name to a variable. Let me just leave this with you:

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

All this is especially important when working in a team with other developers. When everyone writes code while following the same conventions, it becomes easier to predict from where to import function X, how to use function Y, etc.

To abide by PEP8 standards, we are using a linter called flake8 which prevents poorly-styled code from reaching production.

Your code is your documentation

I'm a big believer that code should be self-explanatory. When you have to add comments to explain something, it means that your code is too complex. Try to simplify it.

Adding comments as documentation, on the other hand, is a pitfall I encountered multiple times. It is just too hard to keep that "documentation" up-to-date, and you will forget to update it.

So try and keep your code simple enough so it is easy enough to read. In those cases when you really can't, make sure to be precise while documenting.

Where did this get us?

And finally, if we apply the advice, we'll end up with something like this:

FILTER_KEYWORDS = ("sandbox", "mongo", "postgres", "memcached")

data = []
logs = stdout.decode('utf-8').split('\n')

for line in logs[1:]:
    for keyword in FILTER_KEYWORDS:
        if keyword in line:
            data.append(line.split())
            break

This post just scratches the surface of how to write better code. To find out more, I really recommend a book called Clean Code.