In the process of writing a project, it is inevitable to name various methods and variables. You must have experienced times when it was extremely difficult to name variables. Sometimes naming seems easy, such as when adding a new domain entity. Let's take user as an example. The addUser method may have been created without any further thinking. The work is completed, congratulations.
But is this really the case? How many students discovered that other students' interfaces used the saveXxx naming method when they were reviewing the code? Should I align with him? Or continue to go your own way?
This situation does arise if naming conventions are not clear within the team. A more serious question than it seems on the surface is: are save and add really the same? If there is no unified naming convention, there may be language differences between save and add. When others see that your interface naming is different, and your comments are not so complete. If the student who uses your interface is conscientious, he may spend time to confirm whether your underlying business logic is consistent. Or you can put this question aside for a while and let it be tested again during the self-test.
This question is difficult to answer directly. But although we cannot accurately describe a concept, we can use a series of descriptions to outline the outline of naming:
Then every time you name an object, you can quickly recall the list in your mind , see if he meets the above content. You may need to check the Check List at first, but once you become proficient in this step, you can make a quick judgment: "The current one is not good enough, let me think about it again."
Check List alone is not completely enough, we also need to understand the concept. Ability to quickly reflect scenarios and use counterexamples to determine whether conditions are met.
Just as the text says
I think this is the best one to understand. Good code should be interpretable, and the naming can express the "action" you want to perform. What you might need, and what you'd like to change. It would be better to name it endTime instead of t. Similarly, what is i in the for loop needs to be remembered when looking at all the logic in for. Then it is better to just name it robotMoveStep, which can also release valuable brain cells. For some magic values ??such as 4, if the context is not known, it is difficult to judge what it refers to. At this time, it is better to use constants instead. Even if the knowledge becomes a class variable, there is still a separate 4. in the code.
Avoid ambiguity
There are several examples of this in Alibaba's code specifications. For example: use uppercase letters to represent the Long type, such as 1L, in order to avoid 11 and 1l (1L The embarrassment of lowercase). The same thing happens if you use some special types of naming, such as userList. It turns out that it is actually an int[]. Maybe its background is that it changed from userList to userIds at the beginning, but no matter what the code Always better than explanation.
No redundant information
Generally speaking, we will not actively add redundant information to names. User is user, but what if it is expanded when you want to add a new subdomain object? userInfo, extendUserInfo, extendUserInfoNew? This is not something that will never happen. In fact, it is precisely because it has happened, and once it happens, it is difficult to adjust, so we must try our best to avoid it. Adding a suffix may seem like a good idea for a simple distinction, but this is actually a problem with "meaning as the text means".
When a new person just sees the name and can't tell the difference between them, then he needs to know them well to be able to develop. Just to ensure that modifying a function is correct, we can only confirm the logic one by one and turn the context upside down. Redundant information is nonsense and meaningless, so it should be removed. If you really need to add distinction, you should add a method that can provide identification capabilities, such as userContactInformation.
Can be retrieved
You can think about it, when a bug occurs, and then students on the other end prompt you that it is due to a problem in transmitting values, and the variable name is sum. Then I think the next step is to confirm what the interface is, and then dive into how to obtain the sum. It may be that after a long time, you realize that the sum is not even processed in your code. obtained, but obtained directly through the downstream system. There is really no good way, because sum is everywhere in the project. What if the name is not sum, but totalUserSubmitCount? I think with the help of IDEA, the next step should be global search, and such a precise name does not involve so many problems. Of course, this does not mean that you cannot use names like sum and count, but if you do, you should try to keep them as local variables in a method.
Untyped encoding
Java is a strongly typed language. You do not need to specify its type, so names such as mobileStr are actually redundant. String mobile; just It is enough, and when one day mobileStr becomes Long mobileStr, it will not cause additional misunderstandings.
Distinguish between method and class name
Java is an object-oriented language, so a class should be an object described, so when we describe an object, it should be a noun; The methods in the object should be the capabilities of the object, so describing the method should be a verb.
Unified naming
As mentioned at the beginning, generally speaking, for save and add, their common semantics are different. If they are mixed, people who have suffered a loss will be confused. Be careful when looking at all your code. So what is the difference between get and find? If this concept is not unified, then you need to remember that the guy next door uses find; the guy next door’s save does not actually update the existing object; the guy next door’s add method actually uses the append function.
In addition to developers, this naming should also be consistent with the naming of the field itself. In this way, even when communicating with the corresponding products or business parties, there is no need to make mental conversions in the mind, which can greatly improve communication efficiency. For example, if there are business employees and individual users in two fields, then using customer and employee directly can be understood by everyone smoothly, but if you want to call user and userV2, you may have to make another appointment.
But if this aspect no longer involves domain information, then try to unify it with nouns in the industry, such as redis's aof, or mysql's binlog, which already exists and has a certain context. The name can increase the speed at which others understand your business.
Pay special attention to the fact that this "naming" is the same as its Chinese description name.
Create appropriate context for naming
Because the names themselves are explanatory, contextual information can be provided when naming groups of groups.
For example, if there is a set of methods login() and logoff(), it seems to be used for logging in and out; or if there is a set of attributes such as: price, payTime, couponCode, then it seems to be order-related objects. When a group of interactive names are put together in this way, it can provide a context for the supported objects and businesses, thereby helping to understand the business process.
But try to avoid adding meaningless contexts, such as orderPrice, orderPayTime, and orderCouponCode. Then the order among them is obviously meaningless because it will not help with the naming of attributes. Try When obtaining the actual value, we usually use order.getOrderPrice(), so the order at this time becomes more redundant.
This article adds my own personal understanding based on the many examples listed in "Clean Code". Of course, I also ignore some of the points mentioned in the book and think it is not a problem or the problem is not too serious: such as "try to use names that can be read", and you can use Chinese when communicating; and "don't act cute", In the current relatively complicated environment, everyone is relatively professional, and the probability of occurrence is relatively small.
Of course, each team has its own set of specifications. Generally speaking, it can make coding smoother, and our goal is achieved.