The Forkless Philosopher
On Naming
General principle
Naming, be it for variables, methods or classes should be as precise as
possible and describe what is meant as complete as possible. Where
applicable use domain-specific language. And try to find the shortest
possible description - overly long names make for code that is hard to
read (CTheStuffThatCanBeFoundInBellyButtons
looks awkward;
CNavelFluff
is much better).
Let Method Names Describe What The Method Does
Be as verbose as you can, especially for public methods. Verbosity
not only makes your code easier to read and to understand, it also
is a useful tool to eliminate boolean arguments, which otherwise would
have to be looked up in the documentation by whoever tries to analyze
what the code does.
Example: in some class you have the methods writeToDisk()
and writeToDisk(bool makebackup)
. All
writeToDisk()
does is call
writeToDisk(false)
; to avoid code duplication
all the logic resides in writeToDisk(bool makebackup)
.
Now think about how the code will look like at the place where the
class is used (assuming you want to make a backup):
[...] myReport.writeToDisk(true); [...]
. You can not,
just by looking at the code, tell what writeToDisk
is
supposed to do. Instead, you will have to find the documentation
and then look up what setting the boolean argument to true
means for the behaviour.
But it is easy to fix this: make
writeToDisk(bool makebackup)
private and expose the behaviour by the two more verbose public
methods writeToDiskWithoutBackup()
and
writeToDiskWithBackup()
. You might end up with one
method more than would be strictly necessary, but legibility is
greatly improved.
Use Plain English
No matter what language you choose to use when naming your variables,
methods and classes, choose method names that tell a story. E.g.:
instead of double price = extractPrice(webpage);
be
more verbose and use
double price = extractSharePriceFrom(webpage);
Acronyms And Abbreviations
BTW, in that MMORPG where the BFG is always hidden in the same
spot... if you can understand that small fragment you have probably
some experience with Massive Multiplayer Online Role Playing
Games and you probably have played a game as well where the
most sought-after weapon is a Big F***ing Gun. If not, you
might have wondered what I was talking about.
And that's the problem with acronyms (and usually with abbreviations
as well): they are highly domain specific, and if your knowledge of
that domain is somewhat lacking then you need to look them up. But
where? You can call yourself lucky if the source you are looking at
came with some sort of documentation; to expect a glossary as well
would be pushing it somewhat.
Which leads us to the question: should we use acronyms or
abbreviations in source code? And the answer is: it depends.
An "i" instead of "index" in loops is pretty
much industry standard since the days when Fortran first saw the
light of day; using "r" and "c" in nested
loops that work on a table is not, but might be understood
in the context of rows and cells.
Which gives us a hint: in a restricted context more is permissible
than in a larger or even global scope, and the more generally
accepted an abbreviation or acronym is, the more prermissible
it is to use it. You may instantiate CPlantNameList
as "pnl" if "pnl" is only used in the next
few lines, but don't declare a member attribute in that way:
CPlantNameList mPNL;
is not a good idea.
Declaring an argument that represents a connection as "con"
as in getWebPage(string url, CWebConnection con)
is ok
(methods shouldn't cover too many lines anyway) but again, declaring
a member ttribute CWebConnection mCon;
is not.
- camel-casing vs. full capitalization in acronyms
- short form mixed with long form
- don't override acronyms in mixed language domain sources
CPlantNameList* pPNL;
.
Or should that be CPlantNameList* pPnl;
? There is room
for debate here, since in the camel-casing naming convention normaly
only the first letter of each word is uppercased. But is an acronym
a word in itself? I have come across the problem only once in some
book or article, and there the preferred notation was to keep
acronyms uppercased because it reflects their real life usage.
E.g.: make it mSSLConnection
and not
mSslConnection
. It is up to you to decide, but whatever
your decision is: stick to it and don't mix the two styles! I
have come across this issue with XML tags and my first reaction was:
isn't this a typo? Sadly enough, it wasn't.The second issue is closely related to the first and deals with using the acronym or using the long form. Again, the rule here should be: don't mix the styles. Don't have two fields like
mDC
and
mAlternatingCurrent
in the same class.
Be consistent, at least within the domain: double mDC;
double mAC;
CPlantNameList mPlantNameList;
is fine, since a list of plant names does not belong to the language
domain of electrical engineering.I mention this because I have encountered such a mix-up in real life as well. At that time I wanted to address some fields in a dataset and I needed the column name for that. The column name was longform, the getter of the corresponding class was shortform, and not only that, it was also the shortform of the word in a different language! Code like that could come straight out of "How To Write Unmaintable Code".
The third issue is about ambiguity. In a web-programming context XML usually stands for "eXtended Markup Language". You may have a class named CChristmasMailingList in that context as well, but please don't refer to it as e.g.
myXML
. Not
only is this a recipie for some nasty bugs, it might also make your
code unmaintainable (at least in a restricted timeframe) for pretty
much everybody else (and that includes you in two years time).