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 whichangle 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.