How to come up with meaningful names for your code

Here is a translation of an article from the Better Programming blog on the Medium website. In it, the Daan programmer shares simple rules, following which you can give good names to functions and variables.



As a developer, you probably spend a lot of time creating variables and inventing their names. Names are everywhere: they are needed for files, classes, methods, and those same variables.
')
Since we spend so much time assigning names, it is very important to do it efficiently. In this article I will tell you about a few simple rules, following which you can create good names. After all, this is a whole art!

Use names that reveal your intentions.

The name should indicate the purpose of the code. Easier said than done, yes? How often do you see variables with names that say nothing about the programmer's intent?

The rule is: if the name requires comments, it does not convey the intention.

In this code snippet, there is a variable by whose name its purpose is not clear:

<?php private $s; // Time in seconds 

The variable $s does not tell us anything and is not associated with a period of time. It is better to choose a name that will indicate what units it is measured in.

One of the names below would be more appropriate.

 <?php private $days_since_creation; private $elapsed_time_in_seconds; private $seconds_since_last_modified; 

Names that express intent make the code easier to understand, and therefore it becomes easier to maintain it too.

You will spend time choosing the right name, but you will save it in the future.

Consider this example:

 <?php function getList() { $list1 = []; foreach ($this->the_list as $x) { if ($x % 2 != 0) { $list1[] = $x; } } return $list1; } function getOddNumbers() { $odd_numbers = []; foreach ($this->numbers as $number) { if (isOdd($number)) { $odd_numbers[] = $number; } } return $odd_numbers; } 

Why is it hard to understand what the getList function getList ? No complex expressions, the code is correctly aligned and formatted, there are only three variables and nothing superfluous.

And now look at the getOddNumbers function. See that she does the same thing as getList ?

Note that the code has not become more complicated or easier. We have kept the number of operators, variables and nesting levels, but now it is becoming more and more clear and transparent.

A small change in the name - and it is already much easier to understand what is happening.

Avoid misinformation.

Try to avoid false associations that distort the purpose of the code.

Do not use words that can be understood not as you intended. For example, do not call the product group productList unless it is really an object of type List . Such a name can lead to false conclusions. It is better to use just products .

Perhaps the worst names for variables start with an uppercase O and a lowercase L , since these characters are very similar to 0 and 1.

Also use caution with names that are only slightly different from each other. How much time will pass until you notice a slight difference between SomeMethodForEfficientHandlingOfFiles in one file and SomeMethodForEfficientStorageOfFiles in another? Agree, at first glance they are identical.

Emphasize meaningful differences.

Using numbering is not the best way to assign names. Such names are not informative, since they do not reveal the intention of the author at all.

Let's look at the following example:

 <?php public function duplicateArray($arr1, &$arr2) { foreach ($arr1 as $key => $value) { $arr2[$key] = $value; } } 

This code snippet will read better if we rename $arr1 and $arr2 to $source and $destination .

Use the names you can say

If you are unable to pronounce the name of the function, it is unlikely that you will be able to talk about it and not sound idiotic. This is actually important because the discussion of the code is part of the programming. Nevertheless, each of us must have met variables with unpronounceable names.

Imagine that you have a variable named $xsq and you often discuss it in a company. And here you are talking to a colleague:
- Well, what about ex-cue?
- With what? With access queue?

Someone from the developers will pronounce the variable name as a word, and someone - as an abbreviation.

Use searchable names

The problem with names consisting of one letter is that they are difficult to find in the code.

The same with numeric constants. It is better to replace them with variables. For example, the usual number 8 can deliver a lot of problems if you need to find something in the code. However, it will be much easier if you replace the number with something like MAX_BLOCKS_DISPLAYED .

The only situation in which it is worth using names from one letter is to invent names for local variables within short methods.

Class member prefixes

Do not use m_ prefixes.

Some developers have a habit of using a prefix with underscore in front of class members. Do not do it this way. Your classes and methods should be compact enough so that you do not need any of these prefixes.

Alternatively, you can use an IDE (or install a plugin), which highlights the variables depending on their scope.

Think of your code as a picnic spot in the forest - leave it cleaner than it was before you came.

Conclusion

This is how the more comprehensible names for the code are created.

Comment, leave your questions and write if you want me to highlight other topics related to programming.

I was inspired by this book by Robert Martin “Clean Code”, which I highly recommend reading.