![]() |
Faoileag's Nest |
| home about soapbox gallery sitemap | |
|
The Forkless Philosopher
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 ( 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. 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 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.
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 [1]. 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) by pretty
much everybody else (and that includes you in two years time).
Sources
[1] "How To Write Unmaintable Code" (http://mindprod.com/jgloss/unmain.html)
|
|
| © 2010, 2011 Dietmar König <mail@faoileag.de> --- last changed December 12, 2011 |