Michael Zuskin

"And God called the light Day, and the darkness he called Night."

The First Book of Moses

Give all entities (classes, objects, functions, variables etc. - but begin from DB tables and their fields!) meaningful, descriptive, self-explanatory names which will produce easily understandable code with no (or minimum) need in comments.

Use widely the words per and by - they really simplify a developer's life! A variable's name cowsPerFarm is better than totalCows, and a function name RetrieveCityByCountry tell us more than retrieveCity, especially if it doesn't have parameters which supply the "by what" information. These words also really simplify writing and reading of financial calculations!

Don't use abstract words like actual and total in database fields and variables names - they will madden you forcing to spend extra time trying to understand what is "actual", what is "not actual" and "total" for which grouping level it is. Is totalCows field total per barn? per farm? per village? per province? per country? per the Universe? If, for example, per farm, then how will you name the total per village? It's also "total"! These words are meaningless without the context which is obvious when a data architect is creating the table ("it's easy - it's total per what I am thinking about just now!"), but foggy later - sometimes it's very difficult to see that context looking at a variable surrounded by hundreds lines of code. So, don't write simply total - write total PER WHAT! Only exact definitions that produce no (or minimum) questions, even if that results in longer fields/variables names! If you don't create DB objects - print this paragraph and pin it in the working place of your DBA/data architect.

*** BAD code: ***

totalSalary = actualSalary * totalHours;

*** GOOD code: ***

salaryPerDay = salaryPerHour * hoursPerDay;

Don't produce different name's versions for a same entity (like employee_id / employee_no / employee_num / emp_id / emp_no / emp_num).

When you use values retrieved from database tables, try to name the corresponding variables exactly by the DB fields (of course, adding naming convention prefixes where needed). But you can feel more freely with local variables' names, especially when you are coding financial calculations while the tables fields are not informative enough (see the previous rule).

The common, obvious practice is to give variables and functions short names. But, sometimes, there are situations when it makes sense to break that rule and use long, "real-English" names which which will clearly describe what they are for.

For example, it can be done when a variable is in a rare use (like an instance var which is referenced only a couple of times), but not a local var mentioned in the code many times. Anyway, don't be afraid to give long names each time you feel it will simplify working with the code. See the difference between

mainFilter = this.GetMainFilter(); // bad...

and

filterBySelectedRowInSummaryWin = this.GetFilterBySelectedRowInSummaryWin(); // good!

As you see, names of variables can tell a whole story! Even if it makes a line too long, there is no problem to break it into two lines - it’s better than to look on a variable having no idea what is stored in it (or to search its declaration in hope that a clarifying comment exists). But remember: names of that style should be an exception, not a rule!

Don't shorten words in names if the produced abbreviation is not more than obvious.

Trying to decrease our scripts’ size, we usually shorten words while creating names of our tables, columns, application objects, scripts and variables. Sometimes we shorten them slightly, sometimes - significantly, it usually depends on a practice existing in the company you are working for. In one of my working places I was suffering from very strict rules of shortening; they shortened everything they saw; they didn’t use vowels except leading ones (wrk - work, crtfc - certificate, insr - insurance etc.) and had other official rules how to remove meat from words leaving only main bones of skeleton (when I didn’t understand one of such "wrds", and it happened a lot, I opened a special list of abbreviations!). These names were understandable only to ancient Egyptians, but not to today's developers who came to work in the project. I was happy when my contract had ended.

In another project, I saw the opposite picture: no shortening at all! OK, sometimes (easy stuff like "id", "sys", "col" or "num"), but usually - full sentences used as names of tables, fields, functions etc. I was reading scripts as if they would be an adventures book, not as programming language code! Initially, I was slightly in shock: how do they do that? Don’t they know that everybody must try to keep their scripts shorter? It was not according to what I had seen in different projects during multiple years of my career... But I want to tell you - it was real pleasure to work on this project! So, accept this shocking and unusual, but great idea: try NOT to shorten words in your objects' names! Of course, only guys who creates new systems (including DB objects) can utilize this advice... If words in the system you are working on have already been mangled, you can do nothing with this - use names as they already exist, don't create versions of names for same entities (consistency is above all!).

Shorten words in names if the produced abbreviation is more than obvious.

Here I list exclusive 4 cases when abbreviations should appear in our code:

1. Abbreviations, used as conventional terms in the business. Such abbreviations (which have become a regular words of the daily work) exist in any project, so, of course, they should be used to name objects.


2. Abbreviations, used as conventional terms by developers community working with a particular programming language or a particular area. For example, each PowerBuilder programmer knows that DS stands for "DataStore", each C/C++ writer knows that "ptr" stands for "pointer", and each database specialist knows the meaning of "PK" and "FK", so there is no point in using the long, not abbreviated form.


3. Long words or word-combinations used in a name of a LOCAL variable appearing in the function many times. In this case you have to add an explanatory comment to the variable's declaration line, for example:
   
   string pcm; // pcm = previous calculation method.


4. Words listed in this table:

Names, describing actions, must express if the action should be done in the future or has been already done in the past.

Giving names to variables and tables' fields, don't force readers to guess an action timing. For example, in one of my project two different tables had fields named calculation_method, but one of them stored the method that should be used in the next calculation, while the second one contained the method having been used in the last calculation. Why not to call the columns calculation_method_to_use and calculation_method_used accordingly if it can improve understanding of the business and SQLs?

What do you think about a Boolean variable named isCalculation? Calculation - what??? How must the condition if (isCalculation) be understood? As you see, no understanding problem exists if the variable is named isCalculationDone (isCalculated) or in the imperative form - doCalculation (or simply calculate).

So, the common advice is to use words do..., ...ToDo, perform..., execute..., ...ToApply etc. for stuff which should take place in the future, and ...Done, ...Performed, ...Executed, ...Occurred, ...Passed, ...Applied etc. for things which have taken place in the past.

Use a naming convention if it exists in your programming language / organization.

IMHO, it's very important to easily distinguish in code between:

• Local variables (including arguments to functions) and instance variables. You are lucky if your IDE "knows" to paint variables of different scope with different colors or make them bold and italic (as my favorite Eclipse does), but if it doesn't - you can use, for example, the following practice: localVariable, _privateInstanceVariable, PublicProperty (we can also add __privateStaticVariable).
  
  
• GUI controls of different types, like lblFirstName (for Label), txtCity (for TextBox), btnCancel (for Button), dgCustomers (for DataGrid) etc.
  
  
• Objects of different classes in frameworks like ADO.NET, for example: cnConnection, cmdCommand, dsDataSet, tblDataTable, rowDataRow, colDataColumn, drDataReader, daDataAdapter...