Get a better and more stable code-base just by applying some of these simple tricks

We’ve all heard about how many WTFs make up good or bad code during code reviews. Approximately one or two WTFs account for pretty awesome code, and if you hear a hundred and some other curse words... Well, yeah, you should probably double check more often. However, have you considered what good code really looks like? Have you also considered what good reviews should look like? In this post, we’ll go over some of our habits and why it’s so important to have Clean Code and Good Reviews.

What clean code looks like

We could try to establish what makes up good code. However, we think it’s easier to sum up a few things that don’t make up good code. Let’s dive in.

1. Compact or genius-code
   For the love of god, don’t flex about how you can cram the same logic in fewer lines. Nobody cares about the amount of characters or lines in the code unless you’re programming for a low-level device with limited Flash Memory (like a micro-controller).
2. The wormhole of cryptic functions
   This is especially frustrating to go through as a reviewer, as you end up having to dig through endless functions that don’t really explain very well what they do in their names. As a result, you end up having to keep a mental map of what everything is doing, and most of the time, it doesn’t seem to make sense.
3. The monolith
   This is the opposite of the wormhole. In this case, a huge chunk of logic is presented to the reviewer, and it’s difficult to get through.
4. The imposter
   No, we’re not talking about Among Us. This happens when a function or variable has a name that doesn’t really correspond well (or even at all) with what it’s actually doing. This is extremely misleading and takes a while to figure out. Usually, this forces the reviewer to enter into every definition as you probably have lost their trust.
5. ...

In essence, clean code should be something you understand just by reading the names of the variables and functions.

The importance of readable code

Clearly communicating your code’s functionality with other team members is more important than anything, as it enables more elegant implementation of future improvements. Moreover, doing this allows you to go through the reviewing process quicker. Overall, communicating the functionality of code starts with making the code itself readable.

Want to clean up even more?

If you want to gather some more information on this best practice, we highly recommend the book Clean Code by Robert C. Martin. The first chapters discuss the very foundation of good code, and you will be surprised that Clean Code has nothing or very little to do with functionality, and more with semantics. Functionality is mostly tested and even validated without reading the code. This is done by testing if the application meets set requirements. The more you know, right? 😜

What a good review looks like

I think most developers see a lot of sense in harboring good code quality. They understand and implement this very well already. So, my next question is: what does a good review look like? What does reviewing code mean anyway?

Peer reviewing

Peer reviews make sure all team members working on the same codebase have seen and reviewed the code that has been created. Usually, they do this to add features or fix bugs. It’s an essential task in any modern team that usually takes up some part of their day.

We believe a team is accountable to provide a product/release at the end of a sprint that should reflect a certain list of acceptance criteria. Since the team is accountable as a whole, they will review all code going into the release. They do this by means of support to other members in case something is not done right or regression is introduced.

Pull/Merge Requests

We hope you’re working with Git or at least a VCS. You will have probably heard about PRs or MRs. They are essentially the same. You want to merge the code from your feature branch into the release. Great! It’s also easy for reviewers because they get a neat list of all the changes! 🙌

But have you ever considered your PR/MR titles and descriptions are, excuse my language, kind of sh*t? I bet they are, because this is one of those very commonly overlooked things.

Mostly when you create a Pull Request, it will auto-fill the title with the latest commit message or the branch name. It’s something. The description is usually empty, so you get something like:

Fixed issue with db adapter

To add to this example’s frustration, it has 13 changes and you have no clue what it has to do with the DB adapter. You cannot find the issue on the Sprint or Kanban board. Now, you’re not even sure if this is supposed to be in the next release. You try to reach out to the author but he’s gone for a walk and his phone is not on. Every time. Again and again.

Here are some good practices:

1. Give the title a meaningful name and start with a ticket number from Jira if you can.
2. Make use of images and emojis where you can, this makes the description and title easier to read.
3. Use markdown in the description. Insert headings and bold text to point out what is important. Structure it in a way that makes sense.

Example of an elaborate title and description from one of my PRs

Focus

As the day goes on, you lose focus. Plan your day in advance. I personally prefer doing reviews first thing in the morning, as I tend to have more focus in that part of the day. This may vary from person to person. The idea is that writing code yourself is often using a different part of your brain in comparison to reviewing someone else’s. That is usually a bit more exhausting.

Time to get clean

We hope we have given you enough motivation to start implementing our clean code and good review practices. Did you learn something? Do you have any questions? Do you have any tips for us? Slide in our DMs, we’re curious! 👋🏼