As developers, we spend most of our time reading other people’s code.
Therefore, to become a better developer, our code must be easy to read, and this starts with using good naming conventions.
Here is a list of advice as detailed in Robert C. Martin’s book titled Clean Code:
Use meaningful names which give the reader clarity
“One difference between a smart programmer and a professional programmer is that the professionals understand that clarity is king. Professionals use their powers for good and write code which others can understand”
Robert C. Martin – Clean Code
If a variable requires a comment, the variable is not meaningful enough.
Like with writing, be clear, not clever with your names. Use nouns for your classes and verbs for your methods, which accurately explain what the code below is doing.
The variable $number, although readable, explains nothing about what it’s used for.
But the variable $numberOfPeopleAttendingConcert does.
Use pronounceable names
Programming is a team game.
A method called convertAddressIntoJSON() is easier to say to a teammate than cadd2json().
Your teammates are more likely to understand the method using pronounceable names.
Add context to variables so they can be understood in isolation
Variables of a Car class grouped together are easy to understand:
- $make
- $model
- $fuelType
- $bodyType
But the variable $make looks confusing when viewed in isolation.
Add context to the variable as if it will be viewed on its own:
- $carMake
- $carModel
- $carFuelType
- $carBodyType
Avoid providing disinformation in your naming conventions
A string data type variable called: $totalNumber is disinformation.
You have a string variable that in isolation looks like an integer. This confuses the reader.
Avoid providing disinformation to the user via your naming conventions
One word per concept to avoid confusion
If you are using a specific word for an action, avoid using the same word for a different action.
Concept 1
Method: subtractItemFromArray
This method removes an item from an array.
Concept 2
Method: subtractNumbers
This method subtracts two numbers from each other.
