The Two Irrefutable Laws of Understandable Code

The developer community has no lack of good advice on effective coding, but the shear volume can be overwhelming.  The Two Irrefutable Laws are a great starting point to keep developers from writing nasty code.  Or if you've been coding for awhile you might still be breaking these laws to increase your productivity.  The truth is, breaking these laws will allow you to be more productive in the short run, but not your team.  Any enterprise-worthy application will be modified by many people, and needs to be quickly understood by those tasked to make changes.

The affects of this lawlessness are contained in code bases in practically every company.  You all have seen what I'm talking about - the code that's hundreds of lines long with if-then-else logic and loops scattered throughout.  It's even worse if large blocks are commented out.  The following rules put a "cap" on this kind of code, so that the results are understandable and maintainable.

Irrefutable Law 1: Understandable code contains short methods

CS nerds will call this cyclomatic complexity. I can't tell you how often I've looked at a code base and seen methods that are hundreds of lines long.  This just doesn't make sense.  In this day and age, every good IDE has a "go deeper" shortcut (F12 in Visual Studio and F3 in Eclipse, for example), making it extremely simple make complex logic understandable if it's moved into several methods.
As a rule of thumb, I try to put one piece of logic in each method.  For instance, let's say we have the following code.

SubmitOrder(Order order)
{
 //if order is not to an international location
 if(order.Country == 'US' && order.State != 'PR')
 {
  doSubmitOrder(order);
 }
}

For those questioning why 'PR' is part of the logic - USPS has deemed Puerto Rico an international location, meaning that all packages much go through customs. Just by asking that question you've added one more thing that your mind has to keep track of. A better way to write this code would be:

SubmitOrder(Order order)
{
 if(isNotInternationalShipping(order))
 {
  doSubmitOrder(order);
 }
}

bool isNotInternationalShipping(order)
{
 return order.Country == 'US' && order.State != 'PR';
}

This way someone can quickly see that submitting the order only happens when the order does not require international shipping. They don't have to know that international shipping includes Puerto Rico. Also note that the comment is gone. Since the method is named well, the comment is not needed. Which brings me to the second law.

Irrefutable Law 2: Understandable code is well named

If we are using Law #1 to break up our code into smaller parts, the smaller parts need to be named well.

Irrefutable Law 2A - Typing is cheap
Stay away from abbreviations. Most developers countering this argument would say that they don't want to spend time typing out long object names. But how many of these developers aren't using code complete? Nowadays you just have to type a few letters of any keyword and up pops the full name. And let's face it - one of the biggest time wasters in the modern IT department is trying to understand bad code. For management this translates into a money pit. So in the end it's much cheaper to write expressive, unambiguous names that self document the code, helping out other developers trying to figure out what the ?!$@ your code is doing.

Irrefutable Law 2B- It's OK if it takes awhile to figure out a good name
My rule of thumb on this is to time box 5 minutes or so. If I can't figure out a good name in that amount of time, I'll move on but make a note to come back to it to refactor. Many times I've had a word that kind of describes the object, but not well, so I'll pull up thesaurus.com to search for exactly what I'm looking for. Also try talking through your options with someone. Sometimes it just takes vocalizing the problem to come up with the right answer.

Hopefully these simple rules will point you in the right direction for writing understandable code. Your fellow developers will thank you for it.