When I started programming I developed a particular code style. This style was defined by how I structure my code, how I name things etc and was heavily influenced by the senior developers I worked with.

Over the years I developed my own personal style which was evolved with every project I did and every book I read. I was looking at old some code I wrote back in the day and saw some things that I no longer do but seemed ok at the time. Since I had a minute I wrote a post about a few of them.

Unnecessary code

Here is a piece of code.

function sayHello(name) {
    if(name=='john'){
        return `hello ${name}`;
    } else {
        return `I don't know anyone named ${name}`;
    }
}

At first glance there is nothing wrong here, it works as advertised. But only after I started working did I realise there is more code than required. This function doesn’t need the else clause because it’s leaving the function if the condition is true.

function sayHello(name) {
    if( name === 'john' ){
        return `hello ${name}`;
    } 
    return `I don't know anyone named ${name}`;
}

It might seem nit-picky but if you sprinkle a bunch of these into your code it ends up looking way more complicated than it really is. It’s not just the else, I try to find any code that can be taken out and take it out. The less code there is the fewer places bugs have to hide.

Long Conditionals

if ( quote.amount > 5000 && quote.status == STATUSES.PENDING && 
        user.receivesEmail == USERSTATUSES.RECEIVES_EMAIL ){
    // do something
}

This is correct, it works but that conditional is too long and unreadable. A better way would be to move your conditionals to their own variables, something like:

const sendWarning = quote.amount > 5000
const isPending = quote.status == STATUSES.PENDING 
const receivesEmail = user.receivesEmail == USERSTATUSES.RECEIVES_EMAIL

if ( sendWarning && isPending && receivesEmail ){
    // do something
}

You could name them whatever you like but it makes it cleaner. And if this is combined with the idea of the small functions, your code basically becomes readable and self-documenting.

Too many comments

Speaking of self-documenting… We were taught that comments should be used to explain your ideas, and you can never have too many comments in code.

That was bad advice.

In reality, you can have too many comments, and if your code needs more comments than code then there is something very wrong you need to look into.

Here’s another piece of code.

function func(var, amt){
    if (var.grade == 'gold'){
        return amt * 0.2
    } else if (var.grade == 'silver'){
        return amt * 0.15
    } else {
        return 0
    }
}

This is a very simple example but demonstrates a point. When Someone else looks at this code they need an extra second for it to sink in, to make it easier we were taught to add comments. The only problem is the comments end up confusing everything even more.

function func(var, amt){
    if (var.grade == 'gold'){
        // if the grade of the customer if gold,
        // return 30 percent
        return amt * 0.2
    } else if (var.grade == 'silver'){
        // silver clients get a 15% discount
        return amt * 0.15
    } else {
        // only gold and silver get discount
        return 0
    }
}

A better approach is to spend more time thinking about the naming of the functions and variables. If they were named properly the whole function would read more English like and the need for comments to explain unreadable code disappears.

const GOLD = 'gold';
const SILVER = 'silver';
const DISCOUNTS = {
    [GOLD]: 0.2,
    [SILVER]: 0.15,
};

/**
 * Get customer discount.
 * @param customer Customer object.
 * @param totalAmount Total Sales amount
 * @returns {number} Discount amount to apply.
 */
function getDiscount(customer, totalAmount) {
    if (customer.grade === GOLD) {
        return totalAmount * DISCOUNTS[GOLD];
    } else if (customer.grade === SILVER) {
        return totalAmount * DISCOUNTS[SILVER];
    }
    return 0;
}

Notes:

• The mistake above is intentional because comments go stale faster than the code does.
• The discounts dictionary and the gold and silver constants are better kept in another file, maybe “constants”?
• “Fewer comments” is not the same as “No documentation”, e.g. the doc-strings.

Don’t get me wrong, there is still a place for comments. They should say what the code can not. However, that can not be every line of code.

Conclusion

The more I learn as a developer, the more I realise there is more to learn. I’ve made it a point to always be learning so my thoughts on the above might change with time. That’s how it should be, and when it does, I’ll write another post showing what I’ve learned.