Faoileag's Nest

My Home On The Net

Faoileag On...

Naming Variables, Methods and Classes

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.
Example: CTransom is domain-specific language and also much shorter than CTheFlatEndOfTheOfVessel.

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 (Documentation? What documentation?)

Example: in some class you have the methods writeToDisk() and writeToDisk(bool makebackup). All writeToDisk() does is calling 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 the argument true you aare passing into writeToDisk(), is supposed to ensure. 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 two public methods with more verbose names:

writeToDiskWithBackup() writeToDiskWithoutBackup()

then you might end up with one more method than is 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);

Now whe know what price is extracted (after all, the page might also list the price of various related ceritificats or options), and, by adding the "From" at the end, we also leave a hint about what the argument is for.

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 definitely be pushing it.

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

CWebConnection mCon;

is not.

Another problem that arises with acronyms is consistency. There are three separate issues here, and I have come across two of them in real life. Much to my chagrin, as I may add:
  1. camel-casing vs. full capitalization in acronyms
  2. short form mixed with long form
  3. don't override acronyms in mixed language domain sources

Issue I:

Issue one arises from the way acronyms are written. Let us take the above example with the plant list again: CPlantNameList mPNL;
Or should that be CPlantNameList mPnl;?
There is room for debate here, since in the camel-casing naming convention normally only the first letter of each word is uppercased. But is an acronym a word in itself?
I have come across the problem in some book or article once, and that author favoured uppercase notation, as it better reflects real life usage. Some years later and I work at a company where the internal coding style mandates camel-casing, i.e. 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.
Which brings us to another point regarding issue one:

Never ever use the two styles simultaneously in the same scope!

Or in other words: code with declarations like this:

CConnection* mSSLConnection;
std::string mSslConnection;

is as bad as it can get. Evil.

Issue II:

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 longform and shortform!

Make sure you never have two fields like mDC and mAlternatingCurrent in the same class (worth of course would be mAC and mAlternatingCurrent).
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".

Issue III:

The third issue is about ambiguity. In a web-programming context XML usually stands for "eXtended Markup Language". You may have a class named ChristmasMailingList 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).