Writing Code for the Next Person
Naming Conventions
Years ago when computers had very limited space, some programming languages used to restrict the length of variable names. One notable example was Fortran (specifically, "Fortran 77" as it is called today). In the old Fortran language, variable names were restricted to 6 characters. The same was true for the C language before C89.
This limit in legacy languages resulted in programmers using very abbreviated variable names that meant something to the programmer, but not to others. Some variable names I've seen over the years could be legitimately described as cryptic.
Today, there are virtually no restrictions on the length of variable names. Even so, I still often see abbreviated variable names where there is no good reason. Having terse, cryptic variable named does not lend to code readability. And while I understand "laziness" might be a contributing factor in some name choices, given that IDEs can help with name completion, there is really very little excuse for using unclear names.
Here are just a few examples where names could be rewritten for clarity.
- dte ➜ distance_to_end
- alloc ➜ allocate
- st ➜ state
The same goes for functions. Make function names clear. One should be able to read the function name and have a pretty good idea of what it will do. Here are a few examples.
- CalcDist() ➜ CalculateDistance()
- ClrKS() ➜ ClearKeyState()
- WWP() ➜ WrapWithPadding()
There are some notable exceptions to what I just suggested. For example, it has been a long-standing tradition to use the letters i, j, and k for loop iterations. I would not suggest refraining from using "i" as a loop iterator in favor of "index" or "loop_counter", as examples, without cause. Doing that would not necessarily add value or make the code more readable. That said, if one is using nested loops where "i" is over some number of elements and "j" is an index into an array for element "i", then it might be reasonable to name "j" as "index" and "i" as "element". Just take steps to make the code readable.
I would, however, discourage use of variable names often found in Windows code like "lpSomeThing" (for "long pointer to SomeThing"). There was a reason Microsoft introduced "long pointers", though their utility has mostly expired. And that only solidifies my opinion that there is no good reason one needs to put the type into the variable name. Microsoft did that with "hBitmap" (handle to a bitmap), "hDC" (handle to a device context), etc. Microsoft also used things like "mTotal" to indicate that the variable is a member of the class. While I understand the motivation, modern IDEs can quickly indicate where variables are defined, so such prefixing is unnecessary. The reason I even mention this at all is that I have actually seen non-Microsoft, non-Windows code following these conventions. In my opinion, this just makes modern code look cryptic and less readable.
A naming convention I do think has some value still (though declining with language advances) is the use of uppercase variable names to represent global variables (e.g., ABC_RESULT_SUCCESS) for some System "ABC" to indicate a successful result code. Global variables are generally discouraged and have been for years, but there is still a place for some globals or, the very least, constants. Differentiating what is global vs. what is a local or class member variable has some utility, if not just keeping with a well-established tradition (like "i" for loop iterators).