Are comments cluttering your code?

Writing code involves communication between you, a computer, and other humans.

When we write code, we give another developer instructions describing what we want the computer to do.

A developer needs to place themselves in the authors’ shoes and understand their thoughts. For this to work, the author must write clearly and explicitly.

Often while developing, we come across projects cluttered with comments describing nearly every line of code. This practice is often taught and encouraged at university or college. However, is it the most effective way to communicate?

Does adding information above our functions and variables help us to get the message across?

Could we write our code so that it is easy to understand in isolation, without the need for these often unnecessary descriptions?

Let’s look at some basic scenarios.

The variable names below aren’t self-explanatory, so the author has added comments to describe what the code does.

// this function deletes a banana
function remove() {}

// sends username and password of the admin to the create user api
function createNew(id, pass) {}

Let’s improve the variable names.

// this function deletes a banana
function deleteBanana() {}

// sends username and password of the admin to the create user api
function createAdminUser(username, password) {}

Now that the code has meaningful variable names, are these comments helping the reader to understand the code?

These type of comments aren’t necessary and use up extra brainpower whilst deciphering the code.

Here we have the same functions without the comments:

function deleteBanana() {}

function createAdminUser(username, password) {}

What does deleteBanana do? It deletes a banana… obviously! What does createAdminUser do? It creates an admin user! 😝 If a variable name makes sense outside of the code’s context, it’s a good name.

“Code is like humour.
When you have to explain it, it’s bad.”
- Cory House

There is growing usage of handy comment-generating libraries; unfortunately these also duplicate information and increase incoherence.

There is nothing more confusing than trying to understand code that describes the same thing differently in two places.

Below are some typical examples of such a library in practice:

// Deletes the Fruit entity with the specified fruitId.
function deleteFruit(int fruitId) { }

// The class definition for the FruitBowl entity.
class FruitBowl {
    // The Banana of the FruitBowl entity.
    static banana
}

// Creates the Admin User entity.
function createAdminUser() { }

Here a developer has modified the functionality yet has forgotten to update the description. Perhaps the new function can create any type of user. However, the comment asserts that it creates admin users. Which is correct?

// Creates the Admin User entity.
function createUser(userRole) {}

Often comments are not updated as the code changes, and these outdated comments will confuse and distract future developers.

In summary, I encourage you not to write pointless comments. They often make the code bloated and more challenging to read.

If a fellow developer comes across a comment, the chances are that they’ll spend unnecessary time trying to understand the author’s intention.

Use comments wisely to clarify the complex parts of your code. Write your code so that it speaks for itself through meaningful names and concise logic.

It’s all about getting the right balance, the clearer we express our intent the easier our software is to maintain and understand.