Quick and easy steps to a maintainable and healthy codebase

As a child, my mom drilled into my sister and I that whenever we slept over at a friends or family members house we should always leave the house equal to or better than we met it. Sometimes this just meant laying the bed we slept on before we left and other times it meant vacuuming, dusting and doing the dishes.

I recently adopted a similar approach to my code. The idea is anytime I open a file I should leave it better than how I met it. This can be time-consuming but it sets me up to have a better codebase. So here are a few quick tricks that can be done to in a short amount of time that will help significantly better your codebase over time.

Rename methods

Many times in the heat of the moment when you are filled with inspiration and on a coding groove we tend to find a quick and slightly ambiguous name for a method, this is not good. Also, as we add features to our application we extend the capabilities of methods in which the name starts not to fully encompass what the method does anymore. This would be a good place to change the method name to something longer and more descriptive. Method names should describe what the method does. For example, If you have a method called add_inventory which adds the inventory of a product to your system and sends a confirmation email about the transaction, this functions should be renamed "add_inventory_and_send_confirmation_email". The name may initially seem too long, but it makes a significant difference in the codes readability and ease to understand.

Remove dead code

This is a big one, it is not uncommon to see blocks of commented out code that you or your teammates had left from a previous session or a function that is no longer getting called anywhere in the codebase. It is always a good idea to take a second and remove this code. It will lead to a less confusing codebase in the future. This also applies to stray comments that no longer have any meaning.

Add comments

One of the most valuable cleaning hacks my dad taught me was to start washing the dishes while cooking. As you finish with an item in the kitchen, you start washing it while you wait for the next phase of whatever you are cooking to complete. This requires a lot of discipline but once you form the habit you realize that you never have that many dishes to do after a cooking session. Commenting code is like this, while you are in the groove of coding it is counter-intuitive for you to start thinking of valuable comments to add to the code you are writing, especially since in that moment the code seems so clear to you, but you should. It is always good practice to write comments on blocks of code anytime you open a file and cannot immediately understand what that block does so that you do not have to waste any time trying to understand it the next time.

Extract a concept into a method

Sometimes when solving a problem in code, our solutions are dense blocks of code with multiple conditionals and sometimes it is better to break down this code into smaller methods so they can be re-used around the codebase and also makes the dense block of code more readable and maintainable. For example, you might have a function that send promotional emails from Monday to Friday, you can break out the part that checks if today is between Monday to Friday and call the function is_weekday. This way this can be used in other places in your code without copying and pasting code and if you have more conditionals in a block of code it becomes more readable.

Following these steps are a quick and easy path to a healthy codebase and make your code easily understandle and maintainable.