Diagnosing your codebase, should I be worried?

It can be hard to find out which state you are in, when you’ve been part of a project for a while. It’s like that bad relationship you were in but never realised until you broke up. Below I’ve listed some of the patterns I consider to be symptoms of “slow death”, together with some active strategies to figure out the severity and maybe even fix it at the same time.

Help, I’m new here!

Probably the best way to find out if your codebase is a good communicator is to onboard new people. They have no context, no deep knowledge about the code so can serve as a gauge for the quality of your code. The key thing here is to limit your onboarding to business knowledge. Do not explain how the code works or why certain pieces of code exist. When you get questions on how this works or why it works, only answer with business language answers! It will pinpoint weak points on your code as that’s where the questions will be about.

Pinpointing is nice, but someone with preconceived ideas about it will have a hard time changing it so it becomes clearer. Allow this new person to refactor until they understand it easily, it reads nicely and follows the business process.

Code Review Hygiene

If you don’t have a ‘new person on old code’, you can still apply the same principle with ‘new code on old people’. With any change/PR, limit any conversation to “business language”. With proper business process knowledge, the code change should be very clear to read and should not trigger questions like “could you explain to me how this works?” or should not take longer than a minute to understand if you try to figure it out yourself. If a Pull Request does not satisfy these requirements, you can have the original committer fix the problem, or as above, you can change the code yourself as part of the code review and part of creating an understanding of what the code does.

How many times do you have to explain your code?

Count how often the following scenarios occur! (do not count business process explanations):

• I document my code to explain what it does
• I document my components to explain what they do
• I ask how a piece of code works
• I was asked how a piece of code works
• I had to take a couple of hours to analyse a piece of code

A higher count and a higher occurrence of these will signal your code needs a boost to stay away from death. A lot of these might be hidden as (silent) “WTF”s when a colleague tries to figure out the answer themselves.

What about business process documentation? Even if your code nicely reflects your business domain, it is probably useful to add some comments explaining that domain. But when you do, focus on high level business language and the global process. Details should still be in the code (as they will change most frequently)

If you keep explaining your code instead of updating it, you will be in “slow death” before you know it. You’ll create a “group think” of technical knowledge you need before you can understand the code. This information is hard to transfer and takes a long time to pick up so it’s better not to have it at all.

The danger zone

A large part of keeping a clean codebase is to identify certain behaviours that stop you from keeping it in good shape, catch yourself in the act and fix the problem when you hear the following:

• “Let’s keep it this way for now and refactor later”
• “Let’s keep it this way, it is how it has been for a long time”

These statements basically mean that you haven’t applied the boyscout rule and your code is now collecting inclarity and problems. They will also have a very high chance of never being fixed.