Code quality: The infinite loop of peer-reviewing
Once Upon A Time
I always like to start off my blogs by giving a nice anecdote. I feel that if we, yes I am talking to you, create a relatable link where we share the same experience, then this blog becomes more fun for me to write, and more importantly, fun for you to read. So, let’s begin!
I graduated from college a year ago, but there is this one project that I will never forget. It was my sophomore year and I was done with my introductory courses and I was moving to more advanced ones. As we know, the more advanced the code becomes, the more professional it has to look like. It has to be more or less progressively going towards the point where it can be accepted in a work environment. So, my mindset was still in the introductory course way of thinking. I wrote a flawless piece of code. Like, it was a work of art, for someone in my level at the time. All the functionalities where there, all the tests passed, and I even did the bonus parts and tested it. At the time, I was on cloud nine!
Anyways, I got my project back and, boom, 75%. I was baffled. I look at the code and all the comments were positive. So, I go to my professor and he says “Your application went above and beyond and did all the things it should have done, and even more! But, your code is poor”. I ask “In what ways?” and he mentions “You have poor code quality”. When I asked how I could increase the code quality, he gave me an extensive answer, and I broke down the answer and I am writing about that in this blog.
Order In The Coderoom
Code is very similar to a book when it comes to formatting. If a book is poorly written with an unarranged train of thought, it becomes very hard to read. If code is badly formatted, the same thing happens. Formatting is such a widespread topic that covers many sub-topics. In every project that you will work on in a professional environment, you will have a certain way of formatting that the developers on that project prefer to do. However, it's important to know that, what people are used to on a specific project, isn’t necessarily the right method of doing things. “This is how we do it” might be the most dangerous statement to hear because there is a process to switch from one way of formatting code to another while still being graceful about it and not causing too much disturbance in the project. Let’s make this visual. Below is an example of poorly formatted code:
Why is this poorly formatted? Well, you probably guessed it. If not, let me tell you. The imports you have at the beginning of the file become more readable when you put them in order. Does not necessarily have to be alphabetical, but the imports with the same packages should be together. IF there is still some confusion, look at the example below:
In here, we can see more order to the imports. Anytime I would like to check for packages by java, they are ordered right below each other, and so on. This might seem trying at first, but it’s very simple actually. For me, I use IntelliJ IDEA for my java development, and this is how I configured my settings:
In that way, anytime you format your code, this is the order that you get. Put in mind, this is for backend Java projects. This of course only scratches the surface of code formatting. If this turns out to be useful, I might be encouraged to release another blog solely talking about formatting with Java, with other languages, other IDE’s, or even for frontend. But for now, let’s keep talking about code quality.
The Only Place Where You Shouldn’t Try To Find The Value Of X
Ok, so, we finished formatting the imports correctly and now its time to start coding! Granted, everything I am about to say, I have been guilty of doing. When writing code, it is really important to make it as understandable and readable for the next person that will inevitably see it. VARIABLE. NAMES.
It is already mentally exhausting enough that programmers have to read a non-natural language, don’t make it even harder by naming your variables unrelated or unclear names to what they actually do. I have seen a variety of variable names, but the one I am about to show you is by far the funniest, and unclearest I have ever seen:
Look, man, I am as much of a fan of Avatar as the next person. But, I see this code and it makes my coffee induced morning code review 10x times harder.
Let’s abstract this even more. The next example is by far my least favorite. Not only is it not understandable, but it’s also not funny. Let’s take a look:
The only acceptable letters in coding are i and j! And Only inside loops! If you can tell me what each variable REALLY stands for, you are an absolute legend. I don’t think I need to explain why this is also an unacceptable way to write you code. It should not be the reviewers, or your colleagues, job to try and decipher this ancient, mystical function that has the audacity to call itself a class.
Now, let's see the right naming convention:
As you can tell, this salary calculator is obviously not correct. But you know what the best part is? The fact that knew it was a salary calculator! All because the variable names were clear and understandable. I could not calculate the value of X in college math courses, so please don’t make me do it when I am programming!
But It Works On My Machine!
Testing. Testing. Testing. Wait… TESTING! The only way to find out that your code is really bullet-proof [or as close as possible], is through testing. There are many scenarios where you write a piece of code, boot up your application, and everything is honky dory, Bob’s your uncle! The moment that someone else tries to run it on their machine or, god forbid, you try to deploy, the code starts crumbling like a stale raisin oatmeal cookie. The reason that is the case some times, is because:
- You might have different settings in your environment (e.g path variables)
- Your IDE might be fixing up some of the issues that the code introduces through some settings you set in the IDE
The beauty about something like Java is that you can “Write once, run everywhere”. So make sure it runs everywhere!
Welcome To Your On-Boarding! Figure Out The Code
Ok, now you have your beautifully formatted code, it has been clearly written down with incredibly clear variable names, and boy oh boy has it been tested. You had a moment of clarity and you wish to switch projects or even companies. The final step before you leave is the handover to your successor of the flawless masterpiece that is your code.
We all know that these handovers can be mentally exhausting. You spend the better half of a week walking through the code and at the end, only 25% of what you said actually sticks to the mind of the new developer. Not only that but, after some time, this information will start to gradually become less and less memorable because let's be real, there are so many more important things we need to remember, like the lyrics to Piano Man.
The best way to ensure that the information is never lost is by documenting it. Yes, there might be some fringe accident where the documentation is lost somehow, but that probably won’t happen. Right? Right.
Thou Shall Be Judged
You know what’s better than two eyes looking at your code. Four. Six even. I am not talking about having a spider review your code [I apologize in advance to you for writing this joke]. Sometimes we think that our code is ironclad, but this isn’t always the case. Something that is very useful is enforcing peer-reviewing. You can do this by setting a minimum number of approvers if you are using a version control software like GitLab or GitHub.
If that is not the case, make it a habit with yourself, and within the team, that you should all look at each others code. Not only does that give you better code, but it also helps spread the knowledge of what the team is doing, across all the team members. Now, here is a meme to thank you for reaching this point of the blog
Conclusion: Read It, Then Read It Again
Treat your code the same way you treat friend group chats on WhatsApp:
- Type it in a way where everyone can understand it, make it readable for all your audiences
- The way you say things are important, no one will understand Spanish if they all only speak English. Unless they go out of their way to find out what you meant by saying that. So just promise me you won’t name one of your variables potato 🥔. Because then your teammates would have to “lookup” what that variable means.
- The same way you make plans that suits the entire group and that everyone can join and have a good time, make it so that your code can be run by anyone and they have a good time running it.
- When you make plans with them, you type out the location, time, and who might be joining. Don’t make it so that your plans with friends have more documentation than your code. Document. Your. Code. Please.
- Last but not least, get ready to receive feedback. Take in that feedback, process it, and work on the improvement points.
Now go out there and write sublime code! Get it? Sublime? Okay, at least I tried…
