Comprehensible Code

My article for PHP Advent 2009, the first in this year’s offerings, has been published: Summary: “Reading code is hard work. Here are some reasons why, along with some tips on how to make it easier for other developers to understand your code.” If you would like to comment on it, please do so here. Thanks!

Are you stuck with a legacy PHP application? You should buy my book because it gives you a step-by-step guide to improving your codebase, all while keeping it running the whole time.

13 thoughts on “Comprehensible Code

  1. Very nice article. I really like the “writing code your code as a teaching exercise” take on this. I am very conscious of writing maintainable code, but I’ve never thought of it quite that way before.

  2. Some really good points and well made. Following a defined set of coding standards/guidelines and favouring readability over complexity is important – for yourself, and others!

    Simple and well thought out code is a joy to come across. Let’s have more of it, please 🙂

  3. One item 1, this is always been an issue. I’ve modified the way I do things to please other people, while not driving me insane. Of course, the next thing would be the tabs vs spaces.

    If you are wondering, I use a modified GNU style of coding, spaces and line up all my equals with in each scope.

  4. nice explanation of why it’s good to write comprehensible code. Hope it will help convince people of the benefits.

    As you say in your last statement, I know I totally forget the logic that got me to write some code a year or so ago. Good writing style + appropriate comments helps me understand my own code, let alone others.

    Shame comments aren’t supported on though..

  5. “In short: when writing code, remember the poor bastard who will have to read your program. That poor bastard may be you, six months from now.”

    Hit the nail on the head there, shall be bookmarking, great article!

  6. Good article. Every developer must read these kind of writings. Educating developers in this direction is obligatory. Thank you.

    I’ve one observation. That “poor bastard”‘s life is easier, in some cases, if there’s a “ton” of inline documentation/comments in the code. You can’t design software for the worst programmer of your team. The code (and you) has to be clever (but not tricky).

  7. Fantastic start to PHP Advant 2009! This very thing is something I’m always encouraging myself and co-workers to improve upon.

  8. This whole concept is really an iterative exercise. I am speaking solely about code that one writes and has to maintain over time. I have found what works for me is to never be opposed to writing code over from scratch. Not entirely from scratch mind you but be willing to make big changes repeatedly over time. Comprehensible code is directly related to having a design that cannot be simplified any further. It’s the complexity of the solution that makes code incomprehensible more than anything else. The iterative part comes in solely for the purpose of taking your solution and figuring out a simpler way to accomplish the same thing whether it be the whole design or just some key functions. There is a saying about complexity that goes like this – “the more complex something is the more labels we need to create to manage it”. This is so true in programming. Personally speaking, having worked on large systems where large volumes of data need to be processed it is a mistake to code for performance. Instead code for simplicity and when the design is as simple as you can make it then go back and tweak for performance.

  9. Paul,

    Your article certainly will be a reference for good programming. I worked in a company that did a lot of incomprehensible things likes using coded names for table’s columns (like a table “emblem” for “e-mail marketing [the app], black list e-mails”).

    This sort of thing is a horrible way to communicate, specially for new programmers.

    We have luck because, in PHP world, we have so many good tools to inspire us with our code (PHPUnit, Solar, ZF, symfony are my preffered!).

    While not entirely related to this article, I will be waiting for your word about design patterns and communication in code.

    @Rodrigo I you can translate the article without problems. Read the Creative Commons license: and give the credits in your post.

  10. I am a huge fan of writing clean, readable code. It’s amazing the mileage you get from simply applying some “extract method” refactoring to some code:

    if (!is_null($this->pattern) && !preg_match($this->pattern, $path)) {
    return false;

    can be refactored to:

    if (!$this->patternMatchesPath($path)) {
    return false;

    and taken one step further:

    if ($this->patternDoesNotMatch($path)) {
    return false;

    When you read that last version it sounds like the proper English sentence “If this pattern does not match path” with no Yoda-like “If not you will” weirdness. Stuff like that is even easier when you use an IDE like Zend Studio that can automatically apply extract method to highlighted code. I wrote a series of blog articles about creating simple code by applying a few rules (more like guidelines)

  11. Hi Paul,

    a well-written and well-argued article. It would be even better though if you added some concrete examples. Yes, I know some of this is subjective, but it is pretty hard to learn good programming practice just be reading prose (as opposed to reading code).

Leave a Reply

Your email address will not be published. Required fields are marked *