What's in a Name

What's in a name? Well, everything. As developers, we spend a great deal of time reading code, both our own and other developers' code. We should be able to jump back into code written last week, a year ago or 10 years ago and be able to easily read it. This all starts with good naming.

Names should be chosen that make the code more readable. Avoid abbreviations, as they often make the code less readable and harder to understand. Indexes are one situation where bending this rule is OK (i.e. i, j, k). But index or position works just as well for these. e for Exception is normally fine too.

Variable names should match the type name. For example, if I have a type call Address, the variable should be called address (or some variation, such as fAddress or pAddress). If I need to use two Address objects in the same scope, I may call one homeAddress and one workAddress.

Modeling Data

When creating type names, be careful to consider what data you are modeling. Choosing a bad name will haunt the code forever. For example, I was working on an attorney case management system project and there was a new requirement to support storing documents with the case. The developer was thinking about the action of uploading documents into the case system, so he named the data type CaseUpload. This is a very confusing name to other developers when they join the project. There is no indication that CaseUpload is actually about documents. And now there have been thousands of lines of code written that refer to CaseUpload. This in turn caused a ripple effect of related type names. When the developer needed to track document types, that type was named CaseUploadType. When the developer needed to track which documents were being actively edited, that type was named CaseUploadEdit.

Another developer was tasked with sending information from the case system to an external client system. Someone had been calling this action bridging, as in bridging data between two systems. So the developer chose BridgeQueue to be the type for tracking a single piece of data to be bridged. This is not a great name. First, a queue is a list of things, not a single thing. Second, there is no information about what it is. The term event was being used to describe these things, so BridgeEvent would have been a better choice.

In a related, intermediate system, the same developer named this same type UploadQueue. I'm assuming that it was because he was thinking about uploading this piece of data. I'm not sure why he didn't call it the same thing, he could have. Uploading and downloading are not great names for types. They are actions not data (and relative, point of view actions at that).

These names are now locked into these systems forever. The level of effort and time to go back and change bad names is usually far too great.

Readable Names

Avoid shortening the variable name, such as a or addr. a has no value to readability whatsoever. addr might work, but address is clear and precise.

A developer I know likes to use returnVal as the name for the variable that will be returned from a method. While the return part if obvious, it makes the heart of the method very much less readable. When reading his code, I find myself continually going back to review how returnVal is actually declared.

Avoid using two variable names that only differ by 1 character. It becomes very easy to mix them up by mistake. For example, in baseball, there are right-handed and left-handed pitchers (and batters too BTW). They are often noted as LHP and RHP. Using names like lhp and rhp can get easily mixed up, causing a very subtle bug. leftHandedPitcher and rightHandedPitcher are better choices.

Maintain Conventions

It is important to be consistent with the use of camelcase, lowercase, or uppercase for types, enums and constants. Many programming languages have particular conventions, but the conventions are not required. Your team should choose a convention for your projects and consider it a requirement.

A common convention is to use camelcase for type names, starting with an uppercase letter and camelcase for variable name, starting with a lowercase.

// Prefer
class MemberAccount
MemberAccount memberAccount;

// Avoid
class memberaccount
class MEMBER_ACCOUNT
class Member_Account
MemberAccount m;
MemberAccount acct;
MemberAccount MemberAccount;

Conventions diverge for the use of constants. Some developers prefer to use all uppercase, with underscores as word separators. This can be fine, as long as readability is maintained. Some developers only partially follow this convention.

// Prefer same convention
enum PermissionType
{
    MANAGE_BUSINESS,
    MANAGE_LOCATION
}

// Avoid different conventions
enum PermissionType
{
    manage_business,
    ManageLocation
}

I prefer to think of constants as member variables that happen to be read-only. My convention for constants matches my convention for member variables. So then in Java for example, this allows my enums to be used in the same way as final members.

enum AddressType
{
    work,
    home
}

class AddressType
{
    static final Integer work = 0;
    static final Integer home = 1;
}

These two type declarations result in the same use:

if (AddressType.work.equals(addressType))

Conclusion

Choosing good names can be hard at times. Extra thought is needed to pick good names, but the payoff will be far more maintainable systems for years to come.