Programmer skills get: some thoughts and understanding on code naming

[[120348]]

A software will be implemented in code. The architecture design or design ideas or patterns behind the code are certainly important, but I think what is more important is good naming. Confusing or wrong naming not only makes it difficult for us to understand the code, but worse, it will mislead our thinking and lead to a completely wrong understanding of the code. On the contrary, good naming can make our code very easy to understand, and can correctly express the essence of things and logic to readers, thereby greatly enhancing the maintainability of the code. Reading articles with good naming is very smooth and enjoyable.

Another point that you may not have realized yet is good naming and good naming habits. Since we are always very demanding on the names of each concept, we will think about whether the concept expressed by the name is correct, whether the name correctly expresses the essence of things or correctly reflects the logic of a certain behavior. Therefore, this good habit of thinking about naming can in turn help us correct some previous wrong designs and code implementations; for example, you may have named a place inaccurately before, and then you find that there is another place later that needs to use this name, and it is more reasonable. So you will find that this name is not suitable for the previous place, so you will think about whether the previous place may need to use another name, or you will find that the design of the previous place is fundamentally problematic. This is an example of how a name can prompt you to think about whether your design is correct.

The main reasons for confusing or incorrect code naming are:

1. Not understanding the nature of things;
2. They understand the nature of things, but do not know the importance of naming or simply do not bother to name them well;
3. I understand the nature of things and know the importance of naming, but I am not able to name things well;

Some ideas for developing good naming habits:

1. Be strict with yourself. When you write code, you should have a strong desire to name each name well and a strict sense of self-discipline.
2. Try to analyze and think about the nature of the thing or logic you are naming. This is very important. If you don’t think deeply, you will make mistakes in naming the thing because you haven’t figured out what the thing you are naming is.
3. On the basis of self-discipline and certain analytical ability, pay attention to the method and technique of naming; know when to use verbs and when to use nouns; and where to put adjectives, verbs, and nouns; that is, you must be able to use the subject, predicate, and object in elementary school;
4. The name of any of your attributes must be consistent with its actual meaning; the actions of any of your methods must be consistent with the meaning of the method's name;
5. The naming of the code can show whether the author has clear ideas when programming. If you don't name a name accurately, it may reflect that you have not yet understood the meaning behind the name.
6. Make sure that the naming style of each similar part of your program is always consistent. Don't use uppercase sometimes and lowercase sometimes; don't use full name sometimes and abbreviation sometimes; don't use Pascal naming sometimes and camel naming or Hungarian naming sometimes;
7. Avoid repeated naming; usually names are nested, such as classes in namespaces and methods in classes. If a concept is expressed in a namespace, it does not need to be expressed again in a class.
8. For attribute or class names, the noun should always come first. The noun determines what the attribute represents, and the preceding part is used to modify the noun. For example, if you have a service and a service about orders, you can name it OrderService. This naming tells us that this is a service and an order service. For example, CancelOrderCommand, when we see this, we know that this is a command, that is, a command, and what is the command? It is a command to cancel an order. CancelOrder means canceling an order.
9. For methods, they should always start with a verb and end with a noun. For example, Order.AddItem(orderItem); indicates that the Order class has a method for adding order items. Add is a verb, which means adding, and Item is a noun, which means order items.
10. In C#, we usually use camel and Pascal naming instead of Hungarian naming. I think there are two main reasons: 1) With the powerful IntelliSense prompt of VS, we don't need to emphasize the type of the variable, but I think this is only a minor reason; 2) The real reason, as I mentioned above, is that the noun of a variable is placed at the beginning, and this noun determines what the variable represents. For example, if there is a variable called totalCount, we know at a glance that it is a count, and then count must be an int or long, so there is no need to emphasize its type. For example, remotingRequest, httpRequest, we also know at a glance that they are requests, one is a remoting request, and the other is an http request. remoting, http are used to modify request. request determines what this variable is (which also means that we know its type), and then remoting, http are used to further explain the business meaning or current context of the request. Just like disabledButton, we know at a glance that this is a button, and then what kind of button is it? It is a disabled button. Therefore, a good name itself will make it easy for us to know what the name is, what its type is, and what business meaning it has, so there is no need to add the type abbreviation as a prefix;
11. Learning more English and reading more naming techniques in excellent foreign open source projects will be of great help to our naming;

Analyze some simple naming problems through some not-so-good code naming

There are many problems in the above code. Let's analyze them one by one:

1. The first letter of the method parameter is sometimes uppercase P and sometimes lowercase p, which is inconsistent;
2. There is extra space after the second parameter, which should not happen;
3. Why is the _paramsTable parameter underlined, while other parameters are not underlined? This is inconsistent.
4. publishRequest belongs to camel naming, while iSignCounter, sStageIsOK belong to another naming, which is often used in C++ and is inconsistent;
5. In the foreach loop, the parameter is named instParam, but the subsequent collection is called arrParams4SignActions. To be more symmetrical, it should be called arrInstParam.
6. There are extra spaces in the first two lines of the method, which makes the code formatting confusing;

From the above code, we can see that many problems can be found just through these details. When we write code, as long as we are more careful and pay more attention to whether the layout is beautiful and consistent, and whether the naming is unified, the code will be much more beautiful. Let's take a look at other codes:

1. In the above code, the naming of the two parameters is inconsistent. In projectid, i is lowercase, but in publishId parameter, i is uppercase. They should be unified as uppercase.
2. The key in ViewData is sometimes all-capitalized UPDATE, and sometimes another name, which is inconsistent;
3. The two ifs marked with red boxes above have only one line of code, but one has brackets and the other does not, which is inconsistent; and there are extra blank lines in the second if, which makes the format confusing;

1. In the above code, the function sometimes uses IList, which is an interface, and sometimes uses Dictionary, which is not an interface. This is inconsistent. Interfaces should be used for both, or none of them should be used.
2. The names of listOriginal and receiverList are inconsistent, either all lists start or all lists end;
3. In the foreach loop, the variable type is TDMSOriginalRequirement, but the variable name is originalItem, and the collection name is listOriginal. The three should be unified; for example, foreach (Assembly assembly in assemblies)
4. + There is no space around the “…”. There should be spaces around the plus sign. This is a confusing and imprecise format.
5. The variable createUser is not ideal. create is a verb, and createUser means to create a user, but what it means here is to create a person, so it should be called createdUser or creator;
6. Why are originalItemFormat and originalItem equivalent in meaning? That doesn't make sense. If they were equivalent, they should have been named originalItemFormat from the beginning. And format is a thing, but what does it count if the verb is put in the first place?

1. Among the several private fields of the above class, some have namespaces, some do not, some have none, or some have both; generally, namespaces are declared above and do not need to appear later;
2. ILog logger; There are two problems with this sentence: 1) Why is there no underscore in logger? It is inconsistent; 2) Why is the class name ILog and the variable name logger? To be consistent, either the class name should be ILogger or the variable name should be _log;

The two private methods above, one starts with uppercase and the other starts with lowercase, which is inconsistent and confusing; they should be consistent;

Summarize

Through the examples above, we know that if we accidentally write an extra space or a blank line, or the capitalization of a letter is inconsistent, it will lead to inconsistent naming; if we do not develop the habit of paying attention to the consistency of code naming, the code we write may be like the above. I think it is very bad. The examples I gave above are just simple naming. The deeper naming problem, such as how to make the name consistent with the implementation behind it, requires us to practice it constantly. It is not possible to achieve that level in a short time.

I think that naming is the key to:

1) First, you must realize the importance of naming; 2) You must have a correct attitude and write code carefully; 3) You must try hard to consider whether each name is consistent with what it actually does, that is, the accuracy of the naming; 4) You must always pay attention to various consistency of naming;

Developing good naming habits is not for others or the company, but to improve your own programming skills and your ability to understand things.