1. Naming variables, functions etc

The rule that always applies is: reading code is way harder than writing it! The computer will instantly understand any code you write, people won’t. So make your code easy to read for you and for other programmers.

Name your variables, functions, classes, and other code entities according to what they store, what they do, what they return, what they are responsible for. Need to store an object of type Fruit? Name the variable fruit! List of objects of Fruit type? Name it fruits – easy as that! Need a subset of fruits which are ripped? You know it – “rippedFruits”! Obvious? Should be! Readable? It is! Easy to understand at first glance? – yes!

Yet still, one can find names like f, fList, rf in many codebases.

There’s nothing wrong with naming variables like that during prototyping. You need to code the solution before your thought is gone – ok, write it quickly. But rename it soon after so you can understand the algorithm two months later, and your coworkers will not need to investigate what you meant. Nowadays, renaming is easy – simply use the “Refactor/Rename” feature of your IDE to rename all the variable occurrences at once.

Rule number two: naming is hard.

But it’s easier when you keep in mind that one entity should be responsible for one thing (SRP principle). When you try to name a function InsertNameAndGetRole, you should already know that something is wrong – your code smells. Split this function in half into two functions: InsertName and GetRole, so it’s clear what exactly the function returns and how to read it.

It gets harder when you design a class. You may not be sure what the class will be responsible for or how exactly it will work in the beginning. Name it BlaBlaBlaClass (or any other gibberish), so every time you need to use it you will be reminded you need to alter this name. Also you won’t miss it while committing the code to the source control.

Later, when you finish shaping the class, change its name according to what it does when it is ready.

And, as a general rule, the language of IT is English. It helps with avoiding confusion when you need to switch your thinking between your native language (i.e. Spanish), and English, while using external libraries. It also makes it easier for people who don’t know your native language to join the project.

Leave a comment

Your email address will not be published. Required fields are marked *