Coding Tip: Never Mix usage

Through the course of a project’s lifetime it would be going through many changes. New team members, original members leaving the team, design overhaul, requirement changes and what not. We would want the project to be easy to maintain throughout all these changes

There is a lot of information on the subject already, I am just going to mention a couple of points that I learnt that can add to the project maintainability.

The idea is to never mix or confuse the usage of sections of your code. A section of code can be a variable, a function, class or a CSS selector.

I will pick up examples of two instances that I recall from my experience

1. CSS selectors that are used for both presentation and Javascript manipulation

Although this might now be less relevant with the advent of frontend libraries like React or Vue. But since this is about software maintenance there are still a lot of projects that are still using the good old jQuery.

So when you use something like this:

// HTML
<div class="content-box">
   ...
</div>

//CSS
.content-box {
....
}

// Somewhere in a JS file
$('.content-box').someAction(callback)

Now as the project grows a new UI only guy joins the team and they are tasked with changing the styling of your website. That person is just looking at the CSS/HTM, and goes ahead and changes .content-box to something else as per their new CSS framework.

Now your Javascript functionality breaks. This could have been avoided if you had just used one class for CSS and added another one for Javascript only.

// HTML
<div class="content-box action-block">
   ...
</div>

//CSS
.content-box {
....
}

// Somewhere in a JS file
$('.action-block').someAction(callback)

Although this could have been avoided in many other ways like the New Guy being more prudent with their changes or the developer making it move evident somewhere. But this is usually how we have maintenance troubles

2. Confusing Variable names and mixed usage

This is mostly carelessness and is especially true when working with loosely typed languages like PHP and JS, where you can easily assign a totally different type of value to a variable.

So this is how the code goes like;

$users = config('app.user_fields');

$selected = []
foreach($users as $user) {
   $selected[] = $user['field'];
}

$users = User::whereIn('hobby', $selected);
.......

Above code is confusing because when you read it, it is simple to understand code wise, but difficult to understand on a business level the purpose of this code. The variable $users is used for multiple purposes which also increases confusion.

If we change a few names like this

$default_user_hobbies = config('app.default_user_hobbies');

$hobbies = [];
foreach ($default_user_hobbies as $hobby) {
    $hobbies[] = $hobby['name']
}

$users = User::whereIn('hobby', $hobbies);

The refactored code tells you a bit that you are selecting users based on the default hobbies stored in a configuration. Also we don’t have any confusion about what are the contents of a variable at a given point in code.

That’s all that I had and in the end I will say, sometimes we might be writing code that makes maintenance more difficult because of some deadline pressure or just plain laziness, but it is always a good idea to come back to your code and fix the broken pieces.