Best identifier names?

Question

How can I learn to give the best names of variables and functions (any user name in the program).

Answer 1

Practice.

Always think about it whenever you write or read code, including other people's code. Try to figure out what you will do differently in your code and talk to them about it whenever possible (but not attacking it, that would be unpleasant). Ask them questions about why they chose a particular name.

See how well your code reads without comment. If you ever need to comment on the main purpose of what you have named, consider whether it can have a better name.

The most important thing is active mental participation: practice.

Answer 2

Thinking about names seems to be something that some people are unusually bad, and I'm not sure what the cure is. When I was an instructor in commercial training, I often found myself in these situations:

Me: Okay, now you need to create an integer variable to contain the value returned by getchar ().

[Interns start typing, and I wander around the classroom. Most of them are okay, but one sits like a deer frozen in its headlights]

Me: What is the problem?

He: I can't think of a name for a variable!

So, I would call them for this, but I have a feeling that people with this problem are not going to go far in programming. Or maybe the problem is that they go too far ...

Answer 3

This is a subjective question.

I try to ensure that my code aligns with libraries (or at least the standard ones) so that the code is consistent. I would suggest: See how the standard library functions are named. Look for patterns. Find out what the various naming conventions are. See which one makes sense. For example: most Java code uses really big identifier names, Camel body, etc. C uses short / short names. Then there is the Hungarian notation, which was worth the big trouble when the editors were not smart enough to provide you with type information. You probably don't need this at this time.

Answer 4

Joel Spolsky wrote a useful article on Hungarian notation a few years ago. His key insight:

Let's try to come up with an encoding that will ensure that if you ever make this mistake, the code will look just wrong. If the wrong code, at least, looks wrong, then he has the likelihood of a battle with someone working on this code or by looking at this code.

Next, he will show how to rename variables in strict accordance with our code. The bottom line is that avoiding errors is faster and more obvious return on investment than makes our code more "supported".

Answer 5

Read the good code and imitate it. This is a universal way to learn something; just replace the words "read" and "code" with the corresponding words.

Answer 6

A good way to find expressive names begins with a text description that your piece of software actually does. Good candidates for function (method) names are verbs for noun classes. If you are designing first, one method is text analysis .

Answer 7

• (Even if you are just a team of 1) agree with the coding standard with your colleagues so that you all use the same naming conventions. (for example, properties for fast return values ​​are usually used, but the GetXXX or CalculateXXX methods for values ​​that take time to calculate. This convention gives the caller a much better idea of ​​the need to cache the results, etc.). Try using the same names for equivalent concepts (for example, do not mix Array.Count and List.Length, as Microsoft.net did!)

• Try to read your code as if someone wrote it (i.e., forgot everything you know and just read it). Does this make sense? Does this explain everything they need to know in order to understand this? (Probably not, because we all forget to describe things that we “know” or “obvious.” Go back and check the names and documentation so that someone can pick up your code file and understand it easily)

• Keep names short but descriptive. It makes no sense to write a whole sentence, but with autocompletion in most IDEs, it also makes no sense to abbreviate anything if it is not a standard abbreviation.

• Do not lose characters telling someone that this line is a line (general interpretation of Hungarian notation). Use names that describe what something does and how they are used. for example, I use prefixes to indicate use (m = member, i = iterator / index, p = pointer, v = volatile, s = static, etc.). This is important information when accessing a variable, so this is a useful addition to the name. It also allows you to copy a line of code into an email, and the recipient can understand exactly what all the variables mean - the difference between using static volatile and a parameter is usually very important.

• Describe the contents of the variable or the purpose of the method in its name, avoiding technical terms if you do not know that all readers of your code will know what these terms mean. Use the simplest description that you can think of - complex words and technical terms sound reasonable and impressive, but are much more open to misinterpretation (for example, from the top of your head: sort or sort, serialize or save - although these are well-known words in so not very good cases).

• Avoid vague and almost meaningless terms such as "meaning", "type". This is especially true for the properties of the base class, because you get a “type” in the derived class, and you cannot imagine what type if it is a type. Use "JoystickType" or "VehicleType" and the meaning becomes much clearer.

• If you use a value with units, tell people what they have in their name (angleDegrees instead of angles). This simple trick will make your spaceship crash into Mars.

• For C #, C ++, C in Visual Studio, try using AtomineerUtils to add comments to methods, classes, etc. This tool displays automatic documentation from your names, so the better your names, the better the documentation and less effort required to complete the documentation.

Answer 8

Read “Code Completion,” in particular Chapter 11, “Naming.” This is a checklist (from here , free registration is required):

General naming considerations

Does the name indicate a complete and accurate description of what the variable represents? Does this name refer to a real problem, and not to a solution in a programming language? Is this name long enough that you don't need to break it? Are computed values ​​qualifiers, if any, at the end of the name? Does the name use Count or Index instead of Num?

Naming specific types of data

Are loop index names significant (something other than i, j, or k if the loop is longer than one or two lines or nested)? Have all the “temporary” variables been renamed to something more meaningful? Are Boolean variables called so that their values, when true, are understood? Names of numbered types include a prefix or suffix that indicates a category, such as Color_ for Color_Red, Color_Green, Color_Blue, etc.? Are named constants called the abstract objects that they represent, and not the numbers they refer to?

Naming conventions

Is convention consistent between local, class, and global data? Is convention consistent between type names, named constants, enumerated types and variables? Is the agreement with input parameters consistent only with routines in languages ​​that do not enforce them? Is the agreement as compatible with standard language conventions as possible? Are names formatted for readability?

Short Names

Does the code use long names (unless short ones are needed)? Does the code prevent abbreviations that retain only one character? Are all words abbreviated sequentially? Are names spoken? Is it possible to avoid the wrong names? Are short names documented in translation tables?

Common name problems: you avoided ...

... misleading names? ... names with similar meanings? ... names that differ only in one or two characters? ... names similar to similar ones? ... names that use numbers? ... the names are intentionally misspelled to make them shorter? ... names that are usually written in English? ... names that conflict with standard library names or with predefined variable names? ... completely arbitrary names? ... hard to read characters?