Clean Code PHP – Meaningfull names

Clean Code, PHP

Some people asked me, whats the purpose of Clean Code? If it works, then it works? Any good programmer should be able to read any code? Yes, every good programmer can read every code, but that’s not the point. The reason is that the better structure and clean the code is, the faster it can be read, the faster it can be understand. Most of the time code is read, not written. If we spend a bit more time to write code, then we can save a lot of time reading code faster. Then at the end we win time. If someone does not understand the code fully, then the code will be extended by more unclean code. And then you are going for disaster… Do not underestimate the power of Clean Code!

If you have haven’t read “Clean Code” by “Uncle Bob” yet, then you definitely should.  I highly recommend it for every programmer.  I’m going to make a quick overview about how to use Meaningful names in PHP.

Use Intention-Revealing Names

The names of your variables and functions should tell why they exist, what they do and how they are used. If we don’t know why something exists, then how can we know what to do with it? How can we use it correctly?

Bad

$date;
$dateDays;

Good

$creationDate;
$daysSinceCreation;

In the good example I only changed the names, but now you know its the creation date, and not just a date. Even in the Bad example, I was using it for the same purpose. But I did not reveal its intention when defining it.

Avoid Noise words

You should avoid noise words in clean code. If you have a Product class. Then have 2 other classes called ProductInfo and ProductData. You have used different words for the same thing. Data and Info are noise words, just like a, an and the. Only use words that have a meaningful distinction. Using noise words means you are being lazy and you have not used the correct name. If you use intention revealing names, then you can also fix to avoid noise words. Think about it!

Bad

getProductData();
getProductInfo();
getProductRecord();

Good

getProduct();

A product has data and info, and is a record in some way. So please don’t use this. Think before you use Data, Info and Record in your names. Is it really necessary?

Use Pronounceable Names

You should always use names that are pronounceable, don’t use clever shortcuts or word magic. You should be able to easily talk about your code, and if your variable is called Prdct, then its hard to talk about it.

Bad

$ymdstr = date('Y-m-d');

Good

$currentDate = date('Y-m-d');

Maybe ‘ymdstr’ sounds funny and nice to pronounce, no one knows what your talking about unless you explain it. Don’t be tempting to create a separate dictionary, it might sound cool and nice, but trust me. Its not.

Use Searchable Names

Don’t ever use single-letter names as variables in clean code. Its hard to locate them in your code or to search for it. The only exception is i, j and k in a for loop. And the only reason we do this here, because its only used very locally. Only in local and very short methods you can use this. But the bigger the scope of a variable, the longer the name should be. Because the more you will have to reveal its intention.

You should also avoid using meaningless numbers. Use constant variables. If your are using the number 7 for the amount of days in a week, just use a constant variable DAYS_IN_WEEK. Its easier to read, and if we ever have 8 days in a week (who knows we might get a longer weekend one day?). Then its only only one place where we need to change this.

Bad

for ($i = 1; $i <= 7; $i++) {
    
}

Good

const DAYS_IN_WEEK = 7;
for ($i = 1; $i <= DAYS_IN_WEEK; $i++) {

}

Bad

if ($user->access === 2){
    // Edit
}

Good

class User {
    const ACCES_READ = 1;
    const ACCESS_EDIT = 2;
}

if ($user->access === USER::ACCESS_EDIT){
    // Edit
}

In this last example. I don’t know about you, but I did not know what 2 was. But in the good example, it now all makes sense. Its the same program, we only made it more clean. And now we can find out in seconds instead of minutes what it does. We can also search it a lot easier now. Imagine searching for number 2, you will find a lot of results that you don’t need.

Avoid Mental Mapping

Readers of your code should not need to mentally translate the name of your variables in names they know and understand. You should name your variable in the domain terms.

Bad

$euc = ['Brussels', 'London', 'Paris'];

Good

$europeanCapitals = ["Brussels", "London", "Paris"];

Again, what is $euc? I  need to look into the array and see. Oh yea, these are capitals from countries. See I needed to mentaly map it first. If I had just read $europeanCapitals, then it was like. Ah ye these are European capitals, lets move on. Imagine doing this at every single line of the code. Then you need to think more, map everything and reading the code takes a lot more time. What if I mapped it wrong, I need to go back and forward and start imagine the code in my mind. I’m now mapping instead of reading code. Reading code needs to be easy and clean. It needs to be fun to read code, it should not need to be a mental puzzle.

Pick One Word per Concept

Always pick one word per concept. If you are getting data from a database, then always use fetch, retrieve or get. It does not matter how you call it, as long as it means the same in every class in your application. Consistence is very important to avoid confusion.

The same can be said for insert or add. Don’t use add with 2 different meanings. Adding something to the database, or adding a value to a class should not be done with the same name. Name the one add and the other insert. And use this consistent in your application. There is noting worse then to expect add to do one thing, because it have worked the last 10 times. But it now doing something else. Its every programmers worst nightmare. Don’t be the person that creates nightmares please…

Don’t Add Unneeded context

Don’t add context to variables that are not required. If you have a product class, then its obvious that its the name of the product, and the price of the product. You don’t need context that you don’t need. Variable names only need context that it needs, not more and not less.

Bad

class Product {
    private $productName;
    private $productPrice;
}

Good

class Product {
    private $name;
    private $price;
}

Conclusion

There is a lot more to say about Clean Code. I will definitely go over some other concepts of Clean Code in the future. I am a believer, are you?