What is the most important thing that a programmer should do? The textbook answer, “comment everything”, only ensures a minimum viable reusability, especially when nonsense appears like:
causing unsuspecting developers to detour for what could be hours (are office distractions NP-complete?) and jeopardizing the sanity of everyone involved. Don’t get me wrong, great comments are indispensable works of art, but to be able to write them, you must first write a great program.
Then what is a great program? It depends on who you ask. Rails users might argue that a great program says everything it needs to say exactly once in unreasonably concise Ruby, and includes modular unit tests for 100% of the code base. LISP enthusiasts might praise a program for its mind-boggling recursive structure, and its unreasonable efficiency. However, in both of these cases, and always for any novice programmer, the most important feature of a great program is its consistent and correct use of variables.
Put another way: a computer program’s codebase is unsustainable if its variable identifiers can’t be interpreted correctly by developers. This means that calling a variable “temp” or “theAccountNumber” is always a bad idea unless it is actually correct to think of that variable as “the temp variable”, or the only “account number” that that particular program (or section of the program) uses. We are at a point where nearly every bottleneck I encounter in everyday software development is between my mind and an unfamiliar block of code. If there is a chance of confusing anything else with whatever you’re naming, it’s the wrong name.
What is the right name? That’s another question with a multitude of answers. CamelCase with the basic, accurate name of a variable is a good place to start, meaning that if I were to create a variable to hold the text of some person’s additional info popup, it might be a good idea to start with one of the following:
depending on the context, i.e. what the program (or section) is supposed to do. Most developers I have met use the first letter of every variable to encode a bit of extra information, like if I decided to use lower case letters for an instance-level variable:
or possibly prepend a special character for private variables:
As with everything, the key is to use whatever makes the most sense to the people who need to work on it. If we are to sidetrack into a bit of philosophy, accurate naming is what makes all intelligent communication possible. The only thing that allows you to understand my word (“chicane”) is the fact that it has been used in public to refer to some persistent feature of the universe, and therefore anyone else can imagine what I imagine (or check Wikipedia) when I use it. This applies to all formal and mathematical language too: the only thing that is required to understand a given theorem is an accurate understanding of the words that it contains. Be careful, though: accurately understanding some of the words that mathematicians use is a lot harder than it sounds.
Are any non-programmers still paying attention? This part applies to you too. As the old 20th-century paradigm of “files, folders and windows” starts to look more and more passé, why not ditch that menacing behemoth that you call your “backup” and start organizing files by naming them correctly? (Spelling is important!) If you do that, just Gmail them all to yourself, and then they will be archived as reliably as Google is, forever. If you picked the right name for a file, you’ll know what to search for when you need it.
2 thoughts on “Variables”
I agree that naming is more important than comments. A lot of code seems to require comments only because the variable/function names are so poor that you can’t otherwise determine what is happening. A good set of names often helps reduce the commenting need since you can just naturally read the code.
Good point! I’d like to imagine that there is some “perfect” way to write any program that would require no comments at all and explain itself, but in practice, there are usually ideas involved that would only be self-evident to a smaller number of people.