Programming Tips #5 “Readable Code”

December 5th, 2007 • Related • Filed Under

If you're new here, you may want to subscribe to my RSS feed. Thanks for visiting!

kid-n-computer.jpg

Next up on my programming tips series we have another guest post. This one is written by JB.

Make your code readable!

It’s easier to debug, and later to maintain. Make it readable by using descriptive identifiers, properly tabbing the code, and breaking down the application into functional and reuseable pieces. If you write an app like this, just a hundred times more code:

if($c!==mir($c)){$d=strtolower(mirC($c));}else{$d=$c;}

You will find this much more maintainable:

if ($input !== checkForSpellingErrors($input))
{
	$output = strtolower(correctSpelling($input));
}
else
{
	$output = $input;
}

This way two months later you will still remember what each function does and what each function holds.

-

If you have any programming tips that you would like to share with my readers please send them in via my contact form. I will be picking a ‘best tip’ which will be rewarded with a license for Zend Studio Professional.

There Are 20 Responses So Far. »

  1. Comment by Vaidas Žilionis on 5 December 2007:

    HI, what plugin u are using for code highlight?

  2. Comment by Stanislav on 5 December 2007:

    $output = (!hasSpellingErrors($input)) ? $input : correctSpelling($input);

  3. Comment by Vaidas Žilionis on 5 December 2007:

    Stanislav:
    I like too to use your short solution, but it’s not good readable.

  4. Comment by Nick Halstead on 5 December 2007:

    Vaidas, we are using WP-Syntax - link here
    - http://wordpress.org/extend/plugins/wp-syntax/

  5. Comment by Stefan Koopmanschap on 5 December 2007:

    Heh, funny. I just wrote a piece yesterday on readability: http://www.leftontheweb.com/message/Tip_use_clearly_readable_variable_names_and_constants

  6. Comment by Kick The Donkey on 5 December 2007:

    It annoys me to know end when I open up a source code file, and find junk like that in it. Why do people act as if every LF costs them a buck?

    This has been a very good series of articles. The only one that I don’t do is name my variables consistently. Don’t know why. I just can’t get into the habit.

  7. Comment by Alexey Zakhlestin on 5 December 2007:

    I prefer canonical pear-style… It is readable, but it is a bit shorter

    if ($input !== checkForSpellingErrors($input)) {    $output = strtolower(correctSpelling($input));} else {    $output = $input;}Syhi-подсветка кода

  8. Comment by Kaloyan K. Tsvetkov on 5 December 2007:

    I use it like that

    $output = (!hasSpellingErrors($input))
    ? $input
    : correctSpelling($input);

    The best of both worlds - using the “short” syntax, and making it readable :)

  9. Comment by Kaloyan K. Tsvetkov on 5 December 2007:

    Aah, the WordPress formatting fragged up the snippet above :) here’s another try:

    $output = (!hasSpellingErrors($input))
    ? $input
    : correctSpelling($input);

  10. Comment by Kaloyan K. Tsvetkov on 5 December 2007:

    OK, last one :) The lower two lines are indented to make them look “subordinate”


    $output = (!hasSpellingErrors($input))
    ? $input
    : correctSpelling($input);

  11. Comment by Norbert on 5 December 2007:

    I usually find this format more readable:

    $output = $input;
    if ($input !== checkForSpellingErrors($input)) {
    $output = strtolower(correctSpelling($input));
    }

    Also, if, for whatever reason you happen to remove the else branch, you don’t end up with an unitialized variable.

    Regarding maintainability, I’d probably implement something like this:
    $s = new MySpellChecker($input);
    $output = $s->getCorrectSpelling();

    It’s indeed very important to write readable and maintainable code.

  12. Comment by Stefan on 5 December 2007:

    yeah, I also hardly use the short if notation, finding the long notation more readable and so more maintainable.

    in symfony they use a lot of if/endif notation in the templates, which I like less but is more easy to read for designers I guess.

  13. Trackback by PHPDeveloper.org on 5 December 2007:

    Nick Halstead’s Blog: Three New Programming Tips…

    Nick Halstead has posted a few more of his programming tips ……

  14. Comment by Jason Stubbs on 6 December 2007:

    $output = (!hasSpellingErrors($input)) ? $input : correctSpelling($input);

    More readable would be:
    $output = hasSpellingErrors($input) ? correctSpelling($input) : $input;

    I whole-heartedly agree about descriptive variable/function names but I find ternary operators more readable than if/else blocks in simple cases because there is less to interpret and more of the context can be seen. Consider:

    if (hasSpellingErrors($input)) {
    $output = correctSpelling($input);
    } else {
    $output = $input;
    }

    Five lines as instead of one meaning there’s four less lines of surrounding code that can be seen. $output is referenced twice meaning that the reader must confirm that both blocks are changing the same variable.

    When the condition or assignments are more complex, if/else does improve readability.

  15. Comment by fedmich on 9 December 2007:

    Write code for humans not computers… :)

  16. Comment by Doug on 10 December 2007:

    I hate the use of the shorthand if/else in PHP: $output = (!hasSpellingErrors($input)) ? $input : correctSpelling($input);

  17. Comment by foley on 13 December 2007:

    for best readability i structure my conditionals like such:

    when you are using conditionals inside of lets say an html page, it is understandable to try to save space, however when you use that practice inside blocks of php you are shooting yourself in the foot. You may know exactly what it does and to that most of your code most likely looks like that i would guess. however the person that inherits your code, will find it more difficult to enhance or understand what it is you intended that line to do. Remember, its not javascript or pearl ;)

    it is helpful to add a space before and after paramters ( ex: $var = myFunk( $varx );
    this helps when you are rolling through the code and when you tab your cursor over, you’ll get a chance to stop inside vs after.

    also using the verbose conditional structure ( endif , endfor, endwhile ) is sometimes hard to swallow, give it a chance and you will one day wonder why you ever rocked out with curly braces ( unless you like to spend time trying to find where you are inside a conditional ).

    one last hint for now, when you write comments with the double slash mark, you are adding extra processing “//my comment is small” gets converted to “/* my comment is small */ when your script is run. will you notice the difference, i doubt it, but spending that extra few keystrokes is in my mind more then worth it.

    oh yea, and don’t forget to indent ( tab = 4 spaces ) everything! sometimes its ok to use that horizontal scroll bar, for deeply nested structures. *( but if your deeply nested you might want to pull out repeated structures and move them into a new function or method. ( sorry that one was the last hint i promise )

    This is just my way, in the end its about what works for you. I will tell you that in my position i must work at a feverish pace most of the time, and these best practices / tips i follow in every single line of code i write. I haven’t missed a deadline yet and no one has come up to me and asked me wtf was this code trying to do ( since i started using the above methodology ;)

    best of luck to you my fellow dev headz….

  18. Comment by foley on 13 December 2007:

    trying the code again, seems like it didn’t like what i did:


    /* a speedy developer's idea of structure */
    $input = 'some sort of string' ;
    $Spelling_Check = checkForSpellingErrors( $input ) ;

    if ( $input !== $Spelling_Check ) :
    $output = strtolower( correctSpelling( $input ) ) ;
    else :
    $output = $input ;
    endif ;

  19. Trackback by buy adderall without a prescription on 2 January 2008:

    buy adderall without a prescription…

    news…

  20. Trackback by Doxycycline. on 12 January 2008:

    Doxycycline hyclate for dogs….

    Doxycycline 100 mg. Doxycycline for urinary track infections. Doxycycline hyclate. Doxycycline dose for gonnoreah. Alcohol affect doxycycline. Doxycycline….

Post a Response