Why should code be readable? (Irrational Software)

That code should be as clear and intention-revealing as possible seems to be regarded as a truism (at least in Extreme Programming circles). While I certainly believe that this is true (and I get really frustrated with swinish code), I think it’s worth to examine what it means a little.

In our current project, we’re dealing with fairly complex business rules regarding how commissions are to be split between insurance brokers. Even though these rules are documented, such documentation doesn’t cover each and every case. You could certainly derive the correct rules from reading the documentation and asking the good people at the financial department, though.

Documenting the rules in full detail, in “prose”, would require lots of paper. A simpler notation for describing the rules, covering all exceptions and special cases, would be something approximating a programming language. If such a notation should be written on paper, everybody would agree that it must be clear and easily readable. And although people pay lip service to the notion that software source code should be clear and easily readable, much of the code I’ve seen is obscure and hard to read.

We worked on some things a few weeks ago, and the recent days we’ve worked on fixing some bugs in that code. I forget things fast – especially really abstract things – so for me it’s extremely important that I can check what the business rules are by reading the code. If it wasn’t easily read, there would be a tremendous overhead in fixing even simple bugs. If it would be someone other than me that should fix bugs in my code, the overhead would be even bigger.

So, code must be readable because it really is documentation. Over time, it will be the only comprehensive documentation of the business rules. Sure, the business rules are there in the minds of the employees, but to extract them and write them down on paper in such detail as is expressed in a software program is impossible. I can imagine that there are lot of business rules in the world that originate in software flaws, but have become natural to people. If a system would be replaced, the users would require bugs to be implemented! Think about that!

Note: Rajesh Babu commented on this post, bringing more light on the subject and quoting what other people have said about it. (Via Jonas Bengtsson.)

The above was posted to my personal weblog on May 31, 2002. My name is Peter Lindberg and I am a thirtysomething software developer and dad living in Stockholm, Sweden. Here, you’ll find posts in English and Swedish about whatever happens to interest me for the moment.


Related posts:

Posted around the same time:

The seven most recent posts:

  1. Tesugen Replaced (October 7)
  2. My Year of MacBook Troubles (May 16)
  3. Tesugen Turns Five (March 21)
  4. Gustaf Nordenskiöld om keramik kontra kläddesign (December 10, 2006)
  5. Se till att ha två buffertar för oförutsedda utgifter (October 30, 2006)
  6. Bra tips för den som vill börja fondspara (October 7, 2006)
  7. Light-Hearted Parenting Tips (September 16, 2006)