Think before you type – variable names and other entities

Names of variables, functions, arrays, and other data structures are incredibly important in making your code more readable and more maintainable.

Engage Brain

The most important piece of advice to start with is this:

Think before you type anything.

It sounds too simple, but many new or aspiring programmers treat naming things as an afterthought, and end up with unreadable, inappropriate, or simply random names.

Consider variable names. Think first about what the variable will contain, how it will be used, what units it represents. There are some general guidelines present in various coding standards. For example:

  • Variables/objects should be named with nouns. Use the singular form for stand-alone entities, and plural for collections of entities (e.g., arrays, lists, etc.)
  • Procedure (aka function, subroutine, etc.) names should begin with present-tense verbs, because they do something.

It’s a Process

Consider a floating-point variable which will contain the angle in degrees at which a projectile will be launched. You might be surprised at how many people will just choose a random single-letter variable, such as the letter x. Clearly, if you’re going to go with a single-letter name, the letter a is much more appropriate. But that doesn’t tell you much. The name angle is an improvement, but if there are several different angles in the problem, it doesn’t tell you which angle this one is. You might decide to use angle1, angle2, etc., for the various angles in the problem, but then reader has to keep track of how each one maps to its real-world counterpart. launchAngle (or launch_angle) is better, because it states exactly which real-world angle you’re referring to. But is this angle in degrees or radians? Many floating-point implementations of trig functions require radians, but some work with degrees. To minimize surprises, it might be worthwhile to add the units: launchAngleDegrees (or launch_angle_degrees).

Acronyms, Anyone?

Now, that’s a lot of typing, and some folks will say, “That’s a great name and all, but let me just boil it down to an acronym, and put a dictionary of acronyms in a comment block, if I have time later, maybe.” These folks end up with a variable named lad, which may or may not be defined in a comment somewhere else in the code. The reader of the code sees lad and thinks, “What is this lad? Is it a young boy? Is it the name of a dog? Is it Left Anterior Descending artery, Los Angeles Dodgers, Life After Death, Language Acquisition Device, Leukocyte Adhesion Deficiency, Lymphadenopathy, Least Absolute Deviation, Left Axis Deviation, Light Aid Detachment, Latest Arrival Date, Legislative Audit Division, Latin America Division, Logistics Anchor Desk, Liquidated and Ascertained Damages, Local Area Disk, Linger And Die, Louisiana Association of the Deaf, Linear Application Development, Lower Anterior Descending artery, License Application Design, Linear Amplitude Distortion, … , Launch Area Denied, Lyn Aerospace and Defense, Leader Accreditation Department, Limited Authorization Drawing , Learning Aim Database, or something else?”

Silly? Sure. But you get the idea. The name lad is not nearly as good as spelling it all out. Acronyms, unless they are 100% immediately obvious to everyone, should be avoided. Non-obvious acronyms slow down the reader, and thus increase software maintenance costs.

All of this thinking should happen before you start typing any code.

Parting Thoughts

Some teams like Hungarian notation, which prefixes names with data type information. I’m not a fan of this naming convention, because data types can become very complex, the prefix can begin to overshadow the meaningful part of the name, and if the data type ever changes, you have a maintenance task to ensure that all names are updated appropriately.

I do, however, think that pointers (in C, C++, and other languages that support them) should have a ‘p’ prefix on the name, to remind the reader that they’re looking at a pointer variable, and not the entity it points to.

You can read more about writing readable code in this post.

Leave a Reply