Names are everywhere in software. We name our variables, our functions, our arguments, classes, packages, source files, directories, ... What follows are some simple rules for creating good names.
The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.
What does the list represent?
Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.
Of what type is the account list? String? Array of strings? Array of objects?
O? or they look almost entirely like the constants one and zero, respectively.
How long does it take to spot the subtle difference?
How do these different names convey different meanings?
How can you discuss it without sounding like an idiot?
Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text.
What is the number
It hardly seems reasonable to require each new employee to learn yet another encoding “language” in addition to learning the (usually considerable) body of code that they’ll be working in.
Don’t need to prefix member variables with m_ anymore. Your classes and functions should be small enough that you don’t need them.
This is a problem with single-letter variable names. Certainly, a loop counter may be named
l!) if its scope is very small and no other names can conflict with it. This is because those single-letter names for loop counters are traditional. However, in most other contexts a single-letter name is a poor choice.
Classes and objects should have noun or noun phrase names.
Methods should have verb or verb phrase names like
save. Accessors, mutators, and predicates should be named for their value and prefixed with
isaccording to the JavaBean standard.
When constructors are overloaded, use static factory methods or builders with names that describe the arguments.
Is it obvious outside the class body that WD is an acronym for work days per week?
What does add mean? Concate strings? Insert a record in a table? Append a value to the end of an array?
Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth.
AccountVisitormeans a great deal to a programmer who is familiar with the Visitor Pattern.
What does the term "document" mean in the archives domain? Are photos considered documents?
There are a few names which are meaningful in and of themselves—most are not. Instead, you need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. When all else fails, then prefixing the name may be necessary as a last resort.
What does a comma
,mean? How to change all of them for a specific context?
What does the state represent? Condition or country?