Name Assignment: Programmer's Guide
Translation Naming 101: Programmer's Guide
Naming is one of the major difficulties in the development. It’s impossible to calculate how much time we spend thinking about names and trying to figure out the code with bad names. And it doesn't matter if the objects are, methods, classes or something else. It is considered a proven fact that we spend more time reading the code rather than writing it, so good naming rules will make your life easier in the future .
Good names make the code better and cleaner. They help to intuitively determine what each part of the code is responsible for. In the future, it will be easier for other developers to read your code, and for you too.
')
Below we explain the importance of good naming rules and share useful tips.
Methods and variables need to be named according to their purpose. Before choosing a name, understand what this piece of code is responsible for.
Let's analyze the situation when the method returns the string value of the distance between Warsaw and Paris:
The code is simple and seems to work correctly. And if you change the requirements a little? Let's say you need to display the distance in kilometers and miles. To do this, we introduce a class variable instead of the
A new variable must be called one level of abstraction above its value . This means that first of all you need to think about the assignment of a variable. This will help give more common names, but at the same time not too fancy. In other words, the name should assume the purpose of the variable, not its possible values .
So what is our new variable responsible for? It provides the object with the words km or mi. So a variable can be
The distance between Warsaw and Paris is 1591 km, but in miles you get 988. You need to implement a method that returns the correct value. The rule is the same as in the case of the variable
In the future, cities may change, for example, to New York and London. Then the name
Now our methods look like this:
Methods and variables need to be called one level of abstraction higher than their bodies, but the naming of classes obeys another rule . When creating a class, we don’t need to think about the future. Name the class needed based on current assumptions. We do not assume that the machine can acquire the properties of the boat. Consequently, if the application now requires a car, then the class should be called
Child classes should be named in the same way. If we have a
That is, the rule that you need to name one level of abstraction above the content applies to methods and variables, but not classes.
One of the SOLID principles states that each module or class must be responsible for one thing. It is much easier to choose the name of an element if it has only one function.
For example, the only duty of a bottle is to be a container for liquids. You do not need to give the bottle the opportunity to move or do something else that it is not intended for (in the application). What would you call a container for liquids that can move? It's not easy, and the bottle is a pretty simple example. Instead of producing walking (and then, perhaps, dancing, running and talking) bottles, it is better to adhere to the principle of the only duty . Create one class for the container under the liquid, name the
The principle of the only duty applies to variables. Each variable must do one thing, be it a method variable, a class variable, or a variable of a different type. As in the case of a class, it is much easier to invent a variable name that is responsible for one thing.
Good architecture is inseparable from good naming. If you understand what problem the element solves, it will be easier for you to pick a name for it. There is a useful technique that helps you create a good architecture: break down every part of your task into smaller subtasks. Then choose the names will be faster and easier.
Think about it, isn't it better to give names to modules and objects when you know their purpose? Suppose you need to describe the car. It is difficult to enumerate each functionality in one class, but if we divide it into many small parts, we will get the
Every good name, chosen for a variable, method, object or class, will sooner or later make your life easier. This article shows a few simple techniques that will help you choose good names:
Choosing good names should not be difficult. We recommend to spend time on the selection of the correct names, it is worth it.
* * *
This article was inspired by the book “ 99 Bottles of OOP ” written by Sandy Metz and Katrina Owen. Good book. From it you can learn a lot of useful things, including good code refactoring techniques.
Naming is one of the major difficulties in the development. It’s impossible to calculate how much time we spend thinking about names and trying to figure out the code with bad names. And it doesn't matter if the objects are, methods, classes or something else. It is considered a proven fact that we spend more time reading the code rather than writing it, so good naming rules will make your life easier in the future .
Good names make the code better and cleaner. They help to intuitively determine what each part of the code is responsible for. In the future, it will be easier for other developers to read your code, and for you too.
')
Below we explain the importance of good naming rules and share useful tips.
Level of abstraction
Methods and variables need to be named according to their purpose. Before choosing a name, understand what this piece of code is responsible for.
Let's analyze the situation when the method returns the string value of the distance between Warsaw and Paris:
class DistancePresenter def to_s 'The distance between Warsaw and Paris is 1591 km' end end The code is simple and seems to work correctly. And if you change the requirements a little? Let's say you need to display the distance in kilometers and miles. To do this, we introduce a class variable instead of the
km keyword in the to_s method.A new variable must be called one level of abstraction above its value . This means that first of all you need to think about the assignment of a variable. This will help give more common names, but at the same time not too fancy. In other words, the name should assume the purpose of the variable, not its possible values .
So what is our new variable responsible for? It provides the object with the words km or mi. So a variable can be
kilometers_or_miles , but such a name will be at the same level of abstraction as the variable values themselves. If we need the ability to use other units of measurement (for example, days), then the kilometers_or_miles will be incorrect. Need something more general. Once kilometers and miles are units, we can call the variable unit . It turns out to be one level of abstraction higher (more general name) than the assignment of a variable . New class implementation: class DistancePresenter def initialize(unit) @unit = unit end def to_s "The distance between Warsaw and Paris is 1591 #{unit}" end private attr_reader :unit end The distance between Warsaw and Paris is 1591 km, but in miles you get 988. You need to implement a method that returns the correct value. The rule is the same as in the case of the variable
unit . Let's first think about the problem to be solved. The new method should return the values 1591 or 988. It does not matter how the method will do it. You could call it distance_warsaw_paris , but you’ll have the same level of abstraction as the variable. That is, the method name will assume the return values. Too detailed.In the future, cities may change, for example, to New York and London. Then the name
distance_warsaw_paris become obsolete, and it will be labor-intensive to change it throughout the code. It’s better to just call distance. Exactly what you need: one level of abstraction above the body of the method.Now our methods look like this:
class DistancePresenter def initialize(unit) @unit = unit end def to_s "The distance between Warsaw and Paris is #{distance} #{unit}" end private attr_reader :unit def distance if unit == 'km' 1591 else 998 end end end Level of abstraction and class names
Methods and variables need to be called one level of abstraction higher than their bodies, but the naming of classes obeys another rule . When creating a class, we don’t need to think about the future. Name the class needed based on current assumptions. We do not assume that the machine can acquire the properties of the boat. Consequently, if the application now requires a car, then the class should be called
Car , not Vehicle .Child classes should be named in the same way. If we have a
Car class, we can add a specific version, for example, CarPickup for Car machines with a higher load capacity.That is, the rule that you need to name one level of abstraction above the content applies to methods and variables, but not classes.
Principle of sole duty
One of the SOLID principles states that each module or class must be responsible for one thing. It is much easier to choose the name of an element if it has only one function.
For example, the only duty of a bottle is to be a container for liquids. You do not need to give the bottle the opportunity to move or do something else that it is not intended for (in the application). What would you call a container for liquids that can move? It's not easy, and the bottle is a pretty simple example. Instead of producing walking (and then, perhaps, dancing, running and talking) bottles, it is better to adhere to the principle of the only duty . Create one class for the container under the liquid, name the
Bottle , and then create a class to move the bottle - BottleCarrier .The principle of the only duty applies to variables. Each variable must do one thing, be it a method variable, a class variable, or a variable of a different type. As in the case of a class, it is much easier to invent a variable name that is responsible for one thing.
Break everything down into smaller pieces.
Good architecture is inseparable from good naming. If you understand what problem the element solves, it will be easier for you to pick a name for it. There is a useful technique that helps you create a good architecture: break down every part of your task into smaller subtasks. Then choose the names will be faster and easier.
Think about it, isn't it better to give names to modules and objects when you know their purpose? Suppose you need to describe the car. It is difficult to enumerate each functionality in one class, but if we divide it into many small parts, we will get the
Wheel , Tire , steeringWheel and other classes reflecting various components of the car. These small components are easier to pick up the names, and their purpose is easy to determine. So if you find it difficult to name the components, then the architecture probably has some flaws.Total
Every good name, chosen for a variable, method, object or class, will sooner or later make your life easier. This article shows a few simple techniques that will help you choose good names:
- Rise one level of abstraction above the element's body (except for class names).
- The class name must describe its duty.
- Respect the principle of sole duty (one of the SOLID rules).
- Break the task into smaller subtasks.
Choosing good names should not be difficult. We recommend to spend time on the selection of the correct names, it is worth it.
* * *
This article was inspired by the book “ 99 Bottles of OOP ” written by Sandy Metz and Katrina Owen. Good book. From it you can learn a lot of useful things, including good code refactoring techniques.
Source: https://habr.com/ru/post/343932/
All Articles