Comprehensible Code

13 Responses to Comprehensible Code

1. Anthony Gentile says:

   Tue, 01 Dec, 2009 at 15:33

   Nice article! A lot of good points. I’m always cringing at code I’ve written 6 months-6 days ago. :P
2. Rodrigo Ibraim says:

   Tue, 01 Dec, 2009 at 16:04

   Hi, nice article. I’m from brasil and would like to know if I can translate it in portugues and post in my blog?
   tks.
3. Kurt Koppelman says:

   Tue, 01 Dec, 2009 at 16:27

   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.
4. Ben Longden says:

   Tue, 01 Dec, 2009 at 17:38

   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 :-)
5. EllisGL says:

   Tue, 01 Dec, 2009 at 20:51

   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.
6. simon r jones says:

   Wed, 02 Dec, 2009 at 02:47

   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 phpadvent.org though..
7. Ian Jenkins says:

   Wed, 02 Dec, 2009 at 03:59

   “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!
8. Szabolcs Sulik says:

   Thu, 03 Dec, 2009 at 06:31

   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).
9. Peter McWilliams says:

   Thu, 03 Dec, 2009 at 10:11

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

    Thu, 03 Dec, 2009 at 12:01

    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.
11. Eriksen Costa says:

    Sat, 05 Dec, 2009 at 13:16

    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: http://creativecommons.org/licenses/by-sa/3.0/us/ and give the credits in your post.
12. Matthew Purdon says:

    Wed, 30 Dec, 2009 at 13:53

    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)
13. nicl says:

    Wed, 08 Feb, 2012 at 11:02

    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).