4 min. read

March 02, 2020

clean your code!

Do You Have a Code Janitor?

How clean code is achieved through teams.

aphinya picture

Aphinya Dechalert, Senior developer

A code janitor is possibly one of the most underrated people on your team. But before we begin, what exactly is a code janitor?

A code janitor is someone that sits through and checks the quality of your code. They are the person that can objectively see where the logical pitfalls can potentially happen. 

Catching buggy code before it happens is a skill that often comes in the form of a higher-level developer who is experienced in the pains of fixing bugs. They look at your code based on past encounters and forward-thinking skills. 

What exactly do they look for? 

There are a multitude of factors that they look at before leaving you a comment on your code. The main factors often include (but are not limited to):

  • Length

  • Number of arguments

  • Complexity

  • Understandability

  • Nesting depth

  • Comment density

However, when it comes to clean code, you shouldn’t leave everything to your code janitor. Rather, it should be a joint effort so that it frees up your code janitor’s time to contribute meaningfully to your project’s code.

Why?

Because of the time, your code janitor is also a fellow developer on your team. 

As a former code janitor, it can be a cumbersome task when the team is not quite on board with your thought processes and why you choose to reject their code. 

Personally, I don’t do it on purpose. Rather, it’s a balance between long term technical debt and what the business needs at a particular point in time.

How to assign a code janitor

For many small teams, it’s easy to disregard the need for a code janitor — but you need one. Trust me, I’ve been there and it’s not fun when your entire codebase slips into chaos and you’ve watched it get that far because there’s no one to hold the commit floodgates. 

It’s easy to think that your code is perfectly fine when another pair of eyes may be able to see the things that you can’t. The purpose of a code janitor is to moderate your code. Their experiences, thoughts, and perception of the situation may enlighten you on how you’ve been creating your code.

Just because it works doesn’t mean it’s the most efficient or effective methodology. Over and under abstraction is a common issue among junior developers and a good code janitor can spot and advise the potential problem areas.

So how do you pick a code janitor?

The general rule is that the highest senior person often takes the role of the code janitor.

But that can be a cumbersome and time-consuming task for one person. That’s why it’s good to share the load and assign temporary code moderators who also act as mentors within your team.

This works particularly well for large teams where you can run a buddy system that chains each pair up so they’re not reviewing code in isolated islands. The purpose of code moderation before committing to main branches is more to do with cohesiveness and clean code as much as checking if the feature is actually working.

How to help out a code janitor as a team

Cleaning your code up before submitting it can help develop your ability to self-moderate, in addition to reducing your moderator’s workload. Here is a quick guide on how to assess your code before submitting it for review:

Length

A good piece of code is often short in nature. It is written succinctly and contains either a single functionality that has minimal side effects or is an aggregate that puts all the different pieces together.

When this is implemented correctly, the length is generally short in nature.

Argument Count

The more arguments you have, the more you have to track. Then there is the issue of globals and locals. Use your globals sparingly and limit the number of local variables you have. 

Complexity

The level of complexity is determined by another human’s ability to read and comprehend your code. Complexity doesn’t make you look any smarter. Rather, it creates and uses unnecessary memory space — mentally for the developer reading and potentially dealing with your code after, and the compiler.

Simple code is the act of reducing all that is unnecessary, rearranging it in a way that is borderline minimalistic but still highly functional.

Understandability

Understandability is different from complexity. While the two are closely related, understandability is marked by how quickly your code can be processed and digested by another human.

A quick trick is to name your functions, classes, and variables logically and in a way that is easily understood. Avoid acronyms, even if you feel like it’s common knowledge. It only takes one missing support document to create headaches for future developers after you. Don’t try to be edgy or write everything in acronyms. You’re not pre-minifying it for the minifier. 

Nesting Depth

The deeper the nest, the harder it is going to track and trace. Flat code lets you easily inspect and test. They call deeply nested code the ‘Pyramid of Doom’ for a reason — because it creates more interfaces and potential points of failure than it needs.

The deeper the nest, the higher the likelihood that the person behind the code is not fully equipped with the right sort of knowledge to create succinct code.

Final thoughts

Good code is supposed to be self-explanatory — and this is what the code janitor looks for.

A code janitor goes by many names. Sometimes they pop up as the senior developer or engineer. Sometimes they are the tech lead that’s keeping a close eye on everyone in order to ensure that the project is delivered to a certain quality standard.

But essentially, they are a code janitor because they check, clean and cleanse code before it hits user acceptance testing and production. So be kind to your code janitor, especially when they make comments on certain parts of your code.

It’s a slippery slope when your code slides down in overall quality because there is no one to keep a check on your team’s cohesiveness when it comes to code production. It’s one I personally don’t want to go through again.

It’s all for the greater good and future sanity of your team’s ability to implement things in the future.