"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:
string pcm; // pcm = previous calculation method
.amt | amount |
arg | argument |
arr | array |
asc | ascending |
buf | buffer |
calc | calculate, calculation |
col | column |
cnt | count |
ctr | counter |
cust | customer |
curr | current |
def | definition |
del | delete |
desc | description |
dest | destination |
det | detail(s) |
dif | difference |
doc | document |
elig | eligible, eligibility |
emp | employee |
env | environment |
err | error |
exp | expired |
expr | expression |
frag | fragment |
id | identifier |
idx | index |
img | image |
ind | indicator |
ini(t) | initial |
info | information |
ins | insert |
inv | invoice |
qty | quantity |
len | length |
max | maximum |
min | minimum |
misc | miscellaneous |
msg | message |
num | number |
obj | object |
orig | original |
parm | parameter |
pos | position |
prev | previous |
ptr | pointer |
ref | reference |
res | result |
ret | return |
rc | return code |
sel | select |
src | source |
srv | service |
sum | summary |
sys | system |
temp | temporary |
upd | update |
val | value |
win | window |
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:
localVariable
, _privateInstanceVariable
, PublicProperty
(we can also
add __privateStaticVariable
).lblFirstName
(for Label), txtCity
(for TextBox),
btnCancel
(for Button), dgCustomers
(for DataGrid) etc.cnConnection
, cmdCommand
, dsDataSet
, tblDataTable
,
rowDataRow
, colDataColumn
, drDataReader
, daDataAdapter
...
<< prev | CONTENTS | next >> |