There are some rules related to names and comments that we are going to talk about in this article that can help in making Clean Code. If you haven’t read the first two articles that explain what Clean Code is and what the general rules are, you should check them. But if you have already read those, let’s go to naming and comments rules.

Rule nº 8: Names matter

Choose meaningful names

Pick your functions’ and variables’ names carefully; the name should reveal what that function does and what that variable represents. 

If you use this method, for example:

void save() { }

What does its name tell you? Almost nothing.

But if that function saves a new customer into the database, it should look more like this:

void saveCustomerIntoDatabase() { }

Don’t be afraid to make it a long name, it’s really important that the name tells us what that function does.

Variables

“The length of a variable name should be proportional to its scope.” — Robert C. Martin

If you need to make a for loop where the index doesn’t mean anything outside that scope, one letter is fine:

List<int> studentsGrades;

for(int i = 0; i < studentsGrades.length; i++) { }

So in this case, the scope is one line, then only the letter “i” can be enough.

But if you have a variable that has a bigger scope and is going to be used in many places of your application, then its name should be very large explaining what it is. For example:

List<Grades> mathGradesFromAllClasses;

Functions and Classes

For functions and classes it is the opposite, the name should be inversely proportional to its scope. This means that for larger scopes a function or a class name should be shorter, because it is going to be called many times and should be as abstract as possible. For example, if you have a function that gets the user information from the API and your application uses it a lot in many places, it could be called “getUser”. But if you have another function that changes the color from the user’s avatar, it should be called “updateUserAvatarColor”, a much bigger name that tells us the specific thing this function does in a much smaller scope.

Choose searchable names

If you choose to name a variable like this:

var h = 300;

You will never be able to find it in a quick search on your editor. 

But let’s say that this variable holds the Eiffel Tower height, we could rename it like this:

var eiffelTowerHeight = 300;

This is a better name and it will be much easier to find if you search for it.

Avoid negative names

Negative names makes it harder to read, see the following examples:

 

Positive word:

if(cartIsFull) { } 

else { }

In this example, if the cart is not full, it will skip the if condition and will go to the else block.

 

Negative word:

if(cartIsNotEmpty) { }

else { }

In this example, if the cart is full it is because it’s not empty, then it will go to the else block. Do you see that we need to go deeper to understand something that could be more simple?

Don’t use prefixes

Don’t try to make variables shorter by using prefixes. After a while, even you are going to have trouble trying to remember what that means.

 

DON’T do this:

var dateDMY;

 

Do this instead:

var dateDayMonthYearFormat;

Choose names that you can pronounce

If you use names like the last example “dateDMY”, it makes it harder to read your code. I challenge you to try reading out loud, I think you will agree with me. But when you use words that exist and are easy to pronounce like “dateDayMonthYearFormat” from the same example, your brain uses much less effort to read the code.

Be careful with optical illusions

See these examples:

var textFieldNameController;

var textFieldUsernameController;

Do you see that it’s very easy to confuse them? It’s because they are very similar and their only difference is in the middle of the name. One possible solution is to put the different word in front of the name, this way it’s easier to see the difference between them:

var nameTextFieldController;

var userameTextFieldController;

Make meaningful distinction between names

Checkout these examples:

class Product { }

class ProductData { }

class ProductInfo { }

Can you tell me the difference between those classes? Neither can I. It’s because they say the same thing, all the classes have the product information. If they do the same thing, then there must be only one class. If they do different things, then they should have names that show us the difference between them.

Rule nº 9: Avoid comments

Comments lie. This is because we write a comment once and when we come back to that code after some time and make some changes, we usually forget to change the comments because they are easy to ignore. They usually have a grey color that disappears from our attention. They lie because they were made for a code that does not exist anymore. 

Not all comments are bad, but keep in mind to try your best to clean your code before you decide to write a comment.

There are some types of comments that are acceptable, like copyrights, informative comments explaining a pattern (e.g. regEx), warning of consequences (e.g. “Don’t run this test unless you have some time to kill”), TODO comments can be useful (but try to not leave them there when you leave the code, they are probably going to be forgotten) and publics API’s.

If you don’t know if you can or cannot make a comment, pay attention to these details:

  • Don’t use comments to version control, use git for that.
  • Don’t make redundant comments like this one:

//This is the main function

void main() { }

  • Don’t keep commented code. If you are coding and you comment on your code for some reason, once you realize you don’t need that code anymore you should erase it.
  • Never comment about a code that is somewhere else, that code will probably change and this comment will never be updated.

But more importantly: you should only use comments when you fail to make your code express for itself.

 

In the next article we will continue to talk about the rules for Clean Code, more specifically about the rules for functions.

Calm Experts - Logo

Let's have a chat

Learn how we Can help from here to launch.