One of my major goals when embarking on a development project is to
structure the application such that the code documents itself.
Does this mean that I don't comment my code? Of course not!
But I find that if you take on development tasks with the mindset of
"Could a developer with nothing but a business requirements document
work in this environment semi-effectively if all of my comments
vanished?" you would be amazed at the impact it has on your coding
style.
That being said, the biggest concept of self documenting code comes
down to naming. There are two rules of thumb to self documenting
code in this aspect:
- If it looks like a cow and acts like a cow, call it a cow.
- Once you call it a cow, make sure you always call it a cow.
Or in other words, name things as meaningfully as possible and once
you settle into a naming convention do everything you can to not step
out of that convention. One big readability/documentation pet
peeve I have is when developers slip into using non-standard
abbreviations. I have no problem with abbreviations that are
commonly accepted like avg for average but I do have a problem when
looking through source code I see a plethora of either completely
unknown abbreviations or variations of a concept. An example of
variations I commonly see is for datetime values. Date, dte, dt,
dtm, all intermixed in the code. Certainly most of us are
intelligent enough to figure it out, but it does jar the thought
patterns of someone browsing through the code when you change things up
on them.
Methods
When you name a method, do try to describe its intent. Please
don't use generic names like "GetValue", or "GetNext", or
"GetAvg". They are obscure and require the reader to actually
drill into the logic to determine what the method actually does.
Instead use something like "GetCustomerId()" or "GetNextCustomer" or
even "CalculateAvgPrice".
In addition, when naming methods, since they are "actions" I try to
use the verb-noun naming convention. A good example of this is
"DisplayHourlyReport", a bad example is "HandleOutput".
Another advantage to implementing this type of specific naming in
your code is that it can give you an excellent heads up when a method
is trying to do too much. Many coders, including myself, advocate
that a method should be responsible for only one task, and related
tasks even if called in line should be abstracted to their own
methods. When you are attempting to name a method and you find it
difficult because of the scope of the method you should definitely
examine it and see if you can break it up into smaller more specific
pieces.
Variables
Simliar to the principles for naming methods, name your variables
explicitely as to what they accomplish. The worst case scenario
of this would be using a variable "d" which tells me absolutely
nothing. Slightly less harsh would be using "dt, dte, or
date". What is most beneficial to the reader is using a name like
"CurrentDate" or "MeetingDate".
Something many are guilty of, including myself, is the use of
counters like i or j. This is mostly the fault of our coding book
authors since it seems to be in almost any sample code that has a loop
counter. However i and j tell us nothing about the loop.
This also ties to the use of magic numbers in loops. For example,
if we were going to loop the days of the week, many samples would look
like so:
for i = 1 to 7
In this case i doesn't mean anything, and 7 is a "magic
number". Certainly we can infer that someone is looping the days
of the week, but how much more self documenting is this:
for dayInWeek = 1 to NUM_DAYS_IN_WEEK
Yes, it's more verbose and people will whine, but the clarity you
gain in the code is worth having to type NUM_ then ctrl-space to
populate the rest through intellisense. =)
Failing all else, just be consistent
It is what it is. If in C# you decide to write an if statement like this:
if () {
// stuff
}
Then do it all the time. Don't arbitrarily switch to:
if ()
{
// stuff
}
Conclusion
Writing self documenting and easily readable code isn't hard to do,
it just require dedication. What you will find upon doing it is
that:
- Other people will enjoy working with your code more
- It will make you look more professional since it seems you care about others touching the code
- It will help you write better code since it forces you to clearly define what you are doing
Posted
12-06-2005 10:35 AM
by
Eric Wise