Common mistakes that make your code unreadable, and helpful tips to solve them.

The thing that is probably most difficult for a developer is to dive someone else’s code and start working in it. The code of another developer is always scary but here are some guidelines to make it less scary to your co-workers.

Respect each others indenting

One of the things that really triggers my OCD-mind is when multiple types of indenting are used in a project. Reality is that everyone has his own opinion on how things should be indented.

It can be hard to come up to a consensus on indenting but something you could do to make things better is including a .editorconfig file. Here you can specify the indenting rules for each file type. Most IDE’s either support this or have plugins for this (including Sublime Text, Visual Studio Code, …).

Create the .editorconfig file when you start the project. When you come into an existing project, respect the .editorconfig your co-worker has defined!

Don’t make your variable names too broad

Coming up with good variable names is hard. I sometimes even joke it’s the hardest part of my job. But please don’t scare away from it! Having good variable names can make a key difference.

It’s often easy to choose variable names that are way too broad. Try to avoid using names like “item”, “results”, “value”. Instead name what’s in it.

Stay DRY

Don’t Repeat Yourself! This is one that you have heard a thousand times, but it’s just that important. Don’t write the same 5 lines of code 5 times in your project, it will make the code hard to read and it’s terrible for maintainability.

If you are feeling déjà vu when coding, you should probably take a step back and see if you can’t refactor things.

Don’t use acronyms when you don’t need it

Another pitfall in naming your variables is using acronyms for them. It may be obvious for you at the time of writing what the acronym stands for but don’t underestimate how hard it can be for you colleague to figure out.

Each second spend on trying to understand something that could be more obvious is a second you or your co-worker are distracted from understanding the important part of your code.

Don’t leave stuff in comments

You have all been there, you are reading some old code and some (sometimes seemingly important) piece of code is in comments. A lot of questions are going through your head: “why is this in comments?”, “how can this still work whan that part is in comments?”, “will we ever need it again?”.

For me there’s a simple rule: never commit commented code. I’m also pretty brutal when I see some commented code as I often will just delete it because it will only confuse myself and anyone else who tries to read it.

But what if you need that commented code again? Well you have version control for that!

Create good comments

Instead of putting code in comments you should really focus on writing comments that will help your co-workers and your future-self understand the code that you have written.

I generally try to obey two rules:

• Don’t underestimate how hard it is to understand this piece of code.
• Stay brief, developers are lazy and will quickly skip large blocks of text.

Is it hard to describe what happens in 1 or 2 sentences? Than your function might be a bit too big and you should think about refactoring.