Writing Clean Code

“Code is like humour. If you *have* to explain it, it’s really bad”.

I chanced upon this comment in a tweet and really liked it, in the way it conveys how important it is to write easily readable code.

Spending hours in understanding a snippet of code to know what it’s actually doing is stupid. Your eyeballs going up and down the IDE, scrolling through 100s of 1000s of lines of code, changing between files, not really understanding what the hell is happening is the worst. That’s why writing clean code is essential and a basic skill every developer should possess.

Yes, it is really important to write easily understandable code, not only for the sake of you, to easily get the grasp of what you’ve done long after you’ve written it— but also for anybody else who gets to work on the same project later. But what does it actually take to write clean code? What is actually clean code? When do you say your code is clean? I’ve tried to answer all these questions to my level of understanding and knowledge along with some examples.

Let me start with a simple example of a dirty code. Right from day 1 of programming, we’re taught to name our variables a,b,x,y,z. Without attaching any meaning to the names. Even when we write a simple area calculation program, all we write is:

There is nothing wrong with the functionality, it works smooth as expected and gives the output. But the code is not really meaningful in the way it explains what it does. Let me write the same code in a more “clean” way:

Doesn’t the above snippet seem to be more meaningful than the previous one? Don’t you wonder why? It’s because it conveys its purpose very explicitly, in the way it is named and formatted. With sufficient emphasis on naming and spacing, it adds more clarity and meaning to the code. Let’s dive deep into the clean coding practices and understand why it actually matters. This is a very vast topic to cover in a single post. There are multiple parts to this, so keep following and don’t miss out on any of the best practices for clean coding.

Clean code

Beginning with my basic definition of clean code,

Clean code is some code which is easily readable and meaningful code. It usually takes less cognitive effort to understand what’s actually happening and it is always concise to the point.

Writing and maintaining code should be fun. It should make the developer feel engaged. It shouldn’t be really hard to figure out what to do next with the code you have. The basic practice in writing clean code involves avoiding unintuitive names, complex nesting of if-else blocks and big code blocks including others.

Naming Conventions

Naming is the fundamental understanding required to write clean code. Everything has a name in the code. Right from the library to the variables, constants and classes, everything has a unique name. But the way we name actually decides if it is really intent revealing or not. If a class is not named properly, it loses its purpose. No one understands the essence of it when they don’t even know what it means by its name.

Hence the name for a variable, function or class should always be simple and meaningful. One should be able to understand it without diving deep into the intrinsics.

1. Naming variables:

• The name of the variable or constant should directly imply which kind of data is being stored.
• Always name variables/constants with nouns. Example: user, product, customer, database, transaction, etc.
• Alternatively, you could also use a short phrase with an adjective — typically for storing boolean values. For example: isValid, isLoggedIn, etc.
• The name should be more specific and closely related to the business domain. Consider customer over the user in customer-centric scenarios like a e-commerce application or patient/doctor/staff specification instead of user in hospital domain, etc.

2. Naming methods:

• Function are used to perform tasks and operations. Therefore, functions should typically receive a verb as a name. For example: login(), createUser(), database.insert(), etc.
• Alternatively, functions when producing booleans, you could also go for short phrases with adjectives. For example: isValid(…), isEmail(…), isEmpty(…), etc.
• You should try to avoid names like email(), user(), etc. These names sound like properties. Prefer getEmail(), createUser(), etc. instead.

3. Naming classes:

• Classes are used to create objects. They are nothing but the blueprints for the entity being defined.
• Hence the class name should describe the kind of object it will create.
• Good class names — just like good variable and property names — are therefore nouns. For example: User, Product, RootAdministrator, Transaction, Payment, etc.

The key points to remember should be the following:

• Avoid redundant information. E.g: UserWithNameAndAge is more redundant and is very lengthy. Prefer User
• Follow the casing conventions according to the language you’re using. Example: camelCase in Java, snake_case in Python and so on.
• Be consistent in naming your variables/methods. Example: Avoid using getAge(), fetchName(), retrieveMail(). Instead, be consistent and name them getAge(), getName(), and getMail().
• Avoid slang, unclear abbreviations and disinformation(indicative of wrong data structure in the variable name, etc.

Some good examples:

Keep these points in mind, before you make your life hard by naming your variables x, y or z. And try to follow these conventions to write better readable code.

The next post will discuss some other best practices related to writing comments and proper formatting of code for more understandability and readability.

Post your feedbacks and comments. Thanks for reading this!

Join FAUN: Website 💻|Podcast 🎙️|Twitter 🐦|Facebook 👥|Instagram 📷|Facebook Group 🗣️|Linkedin Group 💬| Slack 📱|Cloud Native News 📰|More.

If this post was helpful, please click the clap 👏 button below a few times to show your support for the author 👇