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.
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.
In essence, clean code should be something you understand just by reading the names of the variables and functions.
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.
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? 😜
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 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.
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:
Example of an elaborate title and description from one of my PRs
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.
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! 👋🏼
Written by
Want to know more?