Eric Wise
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 ha..."> Self Documenting Code - Eric Wise - CodeBetter.Com - Stuff you need to Code Better!
 
Eric Wise

Sponsors

The Lounge

Blogs I Read

Fun & Games

Advertisement

Images in this post missing? We recently lost them in a site migration. We're working to restore these as you read this. Should you need an image in an emergency, please contact us at imagehelp@codebetter.com
Self Documenting Code

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:

  1. If it looks like a cow and acts like a cow, call it a cow.
  2. 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:

  1. Other people will enjoy working with your code more
  2. It will make you look more professional since it seems you care about others touching the code
  3. 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

[Advertisement]

Comments

Eber Irigoyen wrote re: Self Documenting Code
on 12-06-2005 1:42 PM
the "i", "j" or "x" in the loop is not that bad most of the times, I only change it's name when it is relevant, but even better than that is to use a

foreach

if possible
Dave Donaldson wrote re: Self Documenting Code
on 12-06-2005 5:39 PM
Good post. Around here I've been given the nickname "Name Nazi" because I'm a complete freak for properly-named methods, variables, properties, etc. I would also argue that using good names is more important to API design than self-documenting code (although if you think about it that's kind of saying the same thing). I posted something similar a while back here http://loudcarrot.com/Blogs/dave/archive/2004/04/29/180.aspx.
Jeff Lynch wrote re: Self Documenting Code
on 12-07-2005 9:09 AM
Eric,

Here's my take on the single biggest reason for following your instructions on creating self-documenting code.

In six months, will YOU (the developer) be able to remember what your code is supposed to be doing?

I don't know about most folks, but I can't remember what I had for lunch last week, let alone what code I wrote six months ago.

Jeff
Jeremy D. Miller wrote re: Self Documenting Code
on 12-09-2005 3:18 PM
Nice post, but make sure you add *well* written unit tests to your list --> http://haacked.com/archive/2005/12/06/11301.aspx
Eric Wise wrote re: Self Documenting Code
on 12-11-2005 4:40 PM
I agree, well written unit tests are a valuable tool. However I was just addressing this article from the production code standpoint. Unit Tests, UML diagrams, etc are all "exterior" to the working application. =)

The point is well taken though that unit tests do not so much document what is happening as well named methods and variables do, but more of how the methods are intended to be used.
Sam wrote re: Self Documenting Code
on 12-17-2005 11:45 AM
Great article! I think Jeff _really_ nailed it on the head with the forgetting what you wrote 6 months ago comment. Though for me it's more like last month. ;)

I whole-heartedly disagree with the "i" for "for" loops though. It's an index, it's rarely used for anything else, and it's a for loop. The actual index of an array is meaningless anyways most of the time. If you're talking about seeing "i" or "j" used for a for-each loop on the other hand, that's just evil and I agree you need to bop those coders upside the head. "ii" for nested loops is really handy too. In the case of nested iterators I think it's more important to make the execution flow as transparent and easy to read as possible more than having good descriptions of the data. I always get tripped up with the flow of nested iterators personally, so I find that really helps.

Jeremy's comment is great too. Who needs examples when you have unit and functional tests?

I also want to ditto everything you said about abbreviation. Hate it hate it hate it. WTF 'reftblcol5'? Why, "Reference Table Column 5" of course! What does that mean? Search me...

Abbreviation is a slippery slope though. I had to force myself not to use it at all for about a year. If a method averages, it's called AverageWhatever, not AvgWhatever. Now I'm a little more comfortable with common abbreviations like that though. The hard part is making sure you keep domain-specific abbreviations out. It's the source of much debate at work (the opposition is wrong of course ;)), but the cost is just too high for the benefits. By using domain specific abbreviations you raise the learning curve for new hires or contractors; since they aren't common to the language the abbreviated forms are often arbitrary and inconsistent between different programs or pages, and what's the value you get out of them? That you saved an extra 10 keystrokes on a method you're only going to half to type a half dozen times in an application?

It amazes me how many coders ignore your common sense guidelines and insist on believing that what limits them is their keyboard.

If your keyboard is your limitation most of the time, then you're either very very very good, or very very very bad. And the number of people that are that good could probably all fit on a 747. ;-)
??? » Blog Archive » Documenting Your Code for Fun and Profit wrote ??? » Blog Archive » Documenting Your Code for Fun and Profit
on 05-22-2008 12:47 PM

Pingback from  ???  » Blog Archive   » Documenting Your Code for Fun and Profit