Meaningful Names

Choosing good names takes time but saves more than it takes. So the idea is to take your time choosing a name and change them when you find a better one. 

Use Intention-Revealing Names

The name should answer the big questions such as why it exists, what it does, and how it is used. If a name requires a comment the name fails to show the intent. 

int d; // elapsed time in day

The name d reveals nothing. It does not show a “time elapsed in day” as the comment claims. A better name could be:

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

TLDR: Variable, Class, Function names – should not need an explanation. 

Avoid Disinformation

• Do not refer to a grouping of accounts as an accountList unless it’s actually a List. The word means something specific to programmers. It might lead to false conclusions. 
  • Instead of accountList, change it to accountGroup or bunchOfAccounts
• Beware of using names that vary slightly. How long does it take you to see the difference between these two names? 
  • XYZControllerForEfficientHandlingOfStrings
  • XYZControllerForEfficientStorageOfStrings

Make Meaningful Distinctions

The idea behind this is to make your names reflect the difference between another name. 

No Noise Words!

Imagine you have a Product class. If you have another called ProductInfo or ProductData, the names are different without meaning anything different. Info and Data are indistinct noise words like “a”,”an”, and “the”. 

Not to say anything is wrong with those words, just that they need to not be used as ways to differentiate two variables. (“theFoo” and “foo”) 

Noise words are redundant. The word table should not appear in a table name. The word variable should not be in a variable name. What’s the difference between NameString and Name? Or imagine finding one class named Customer and another named CustomerObject. 

Here’s another poor example:

getActiveAccout();
getActiveAccounts();
getActiveAccountInfo();

Use Pronounceable Names

If you can’t pronounce it you can’t discuss it without sounding like an idiot. 

An example I read: There was a company with a variable named genymdhms (generation date, year, month, day, hour, minute, and second)  so they walked around saying “gen why emm dee aich emm ess”. This could be a fun joke to have with the way to pronounce it sounding funny but for a new developer coming in, they would need the variable explained to them. 

Why not make the name clearer instead as:

Private Date genymdhms; —-> Private Date generationTimeStamp;

Now you can sound more intelligent. 

Use Searchable Names

Single-letter names and numeric constants are not easily searched for in a program.

You can easily search for MAX_CLASSES_PER_STUDENT, but the number 90 would prove more trouble. 

This includes the letter e which is a very common letter in the English alphabet. Which normally shows up automatically as an eventArgs handler name. 

This excludes single letters in a short method such as seen in a for loop. 

TLDR: Longer names trump shorter names.

Hungarian Notation

In the days of Fortran and Windows C API, the compiler did not check types so programmers relied on a crutch to help them remember types.

Now, compilers remember and enforce the types. So HN and other forms of type encoding are simply obstacles that make it harder to change the name or type of a variable, function, or class. They also make it harder to read the code. And they create the possibility that the encoding system will mislead the reader. 

 PhoneNumber phoneString; // name not changed when type changed!

Class Names

A class name should not be a verb. Classes and objects should have a noun or noun phrase names like Customer, BankAccount, User. Avoid Data, Info, Manager, or Processor. 

Method Names

Methods should have a verb or verb phrase names like postPayment, deletePage, or save. 

Don’t be Cute With Names

Will a new developer know what the HolyHandGrenade function is supposed to do?

Instead, call it simply DeleteItems. Choose clarity over entertainment value. 

deleteAllItems() vs whack() or kill() or eatMyShorts(). 

Say what you mean and mean what you say. 

Pick One Word per Concept

Use the same concept across the project. 

FetchValue() vs GetValue() vs RetrieveVaue()

If you are using getValue() to return data of something, don’t mix and match across the code using fetchValue() or retrieveValue(). It will only confuse readers. 

Don’t Pun

Avoid using the same word for two different purposes. A pun is using the same term for two different ideas. 

Say you have two classes and they both say add() as a method. One class will add 2 values and the other will insert an element into a database. A better way might be to have the second class use insert() or append() rather than add().

Add Meaningful Context when All Else Fails

Imagine having a member variable named state. Without the context of firstName, lastName, and city, you would not automatically know it was part of an address. You can fix this by adding context with “addrState”, “addrFirstName”, and so on. 

Or an even better way would be enclosing the variables inside a class named Address then even the compiler knows that the variables are part of a bigger concept. 

Closing Remarks

People can be afraid of renaming things for fear that other developers will object. I believe we should be grateful when names change for the better. We might end up surprising each other when changing names but it’s just like any other code improvement. The goal of these rules is to improve the readability of the code. In the long run, it will pay off.