Code Simplicity

Readability and Naming Things

Many people think that the readability of code has to do with the letters and symbols used. They believe it is the adding, removing, or changing of those symbols that makes code more readable. In some sense, they’re right. However, the underlying principle is:

Readability of code depends primarily on how space is occupied by letters and symbols.

What does that mean? Well, it means two things:

Code should have the proper amount of white space around it. Not too much, not too little.

There should be the proper amount of space within a line of code to separate out the different parts. Separate actions should generally be on separate lines. Indentation should be used appropriately to group blocks of code.

With this principle, it’s actually the absence of code that makes things readable. This is a general principle of life–for example, if there was no space at all between letters and words in a book, it would be hard to read. On the other hand, it’s easy to see the moon against the clear night, because there’s a lot of clear black space that isn’t the moon. Similarly, when your code has the right amount of space in it, you can tell where and what the code is easily.

For example, this code is hard to read:

x=1+2;y=3+4;z=x+y;print"hello world";print"z is"+z;if(z>y+x){print"error";}

Whereas with the proper spacing in, around, and between the lines, it becomes easy to read:

x = 1 + 2;
y = 3 + 4;
z = x + y;
print "hello world";
print "z is" + z;
if (z > y + x) {
    print "error";
}

There can also be too much or wrong space, however. This code is also hard to read:

    x            =          1+        2;
y = 3            +4;


  z = x    +      y;
print    "hello world"         ;
 print "z is " + z;
if (z  >     y+x)
 {        print "error" ;
        }

Code itself should take up space in proportion to how much meaning it has.

Basically, tiny symbols that mean a lot make code hard to read. Very long names that don’t mean much also make code hard to read. The amount of meaning and the space taken up should be closely related to each other.

For example, this code is unreadable because the names are too small:

q = s(j, f, m);
p(q);

The space those names take up is very little compared to how much meaning they have. However, with appropriately-sized names, it becomes more apparent what that block of code is doing:

quarterly_total = sum(january, february, march);
print(quarterly_total);

On the other hand, if the names are too long compared to how much meaning they represent, then the code becomes hard to read again:

quarterly_total_for_company_x_in_2011_as_of_today = add_all_of_these_together_and_return_the_result(january_total_amount, february_total_amount, march_total_amount);
send_to_screen_and_dont_wait_for_user_to_respond(quarterly_total_for_company_x_in_2011_as_of_today);

This principle applies just as well to entire blocks of code as it does to individual names. We could replace the entire block of code above with a single function call:

print_quarterly_total();

And that is even more readable than any of the previous examples. Even though the name we used–print_quarterly_total–is a bit longer than our other names for things, that’s okay because it represents more meaning than other pieces of code do. In fact, it’s even more readable than our block of code was, by itself. Why is that? Because the code block took up a lot of space for, effectively, very little meaning, and the function takes up a more reasonable amount of space for the same meaning.

If a block of code takes up a lot of space but doesn’t actually have much meaning, then it’s a good candidate for refactoring. For example, here’s a block of code that handles some user input:

x_pressed = false;
y_pressed = false;
if (input == "x") {
    print "You pressed x!";
    x_pressed = true;
}
else if (input == "y") {
    if (not y_pressed) {
        print "You pressed y for the first time!";
        y_pressed = true;
        if (x_pressed) {
            print "You pressed x and then y!";
        }
    }
}

If that were our whole program, that would probably be readable enough. However, if this is within a lot of other code, we could make it more readable like this:

x_pressed = false;
y_pressed = false;
if (input == "x") {
    handle_x(x_pressed);
}
else if (input == "y") {
    handle_y(x_pressed, y_pressed);
}

And we could make it even more readable by reducing it to this:

handle_input(input);

Reading “handle_input” in the middle of our code is much easier than trying to read that whole first block, above, because “handle_input” is taking up the right amount of space, and the block is taking up too much space. Note, however, if we’d done something like h(input) instead, that would be confusing and unreadable because “h” is too short to properly tell us what the code is doing. Also, handle_this_input_and_figure_out_if_it_is_x_or_y_and_then_do_the_right_thing(input) would not only be annoying for a programmer to type, but would also make for unreadable code.

Naming Things

It was once said by a famous programmer that naming things was one of the hardest problems in computer science. These principles of readability give us some good clues on how to name things, though. Basically, the name of a variable, function, etc. should be long enough to fully communicate what it is or does, without being so long that it becomes hard to read.

It’s also important to think about how the function or variable is going to be used. Once we start putting it into lines of code, will it make those lines of code too long for how much meaning they actually have? For example, if you have a function that is only called once, on one line all by itself, with no other code in that line, then it can have a fairly long name. However, a function that you’re going to use frequently in complex expressions should probably have a name that is short (though still long enough to fully communicate what it does).

-Max

86 Responses to Readability and Naming Things

  1. An impressive share! I’ve just forwarded this
    onto a friend who was doing a little homework on this.
    And he actually ordered me breakfast due to the fact that I stumbled upon it for him…
    lol. So let me reword this…. Thank YOU for the meal!!
    But yeah, thanx for spending some time to talk about this topic here on your site.

  2. Good day I am so delighted I found your
    webpage, I really found you by accident, while I was researching on Askjeeve for
    something else, Anyways I am here now and would just
    like to say kudos for a tremendous post and
    a all round interesting blog (I also love the
    theme/design), I don’t have time to browse it all at the moment but I have saved it
    and also added your RSS feeds, so when I have time I will be back to read much
    more, Please do keep up the fantastic job.

  3. I have been surfing online more than 2 hours today, yet I never found any interesting article like yours.
    It is pretty worth enough for me. In my opinion, if all web owners and bloggers made good
    content as you did, the web will be much more
    useful than ever before.

  4. Flora says:

    This excellent website certainly has all of the info I wanted concerning this subject and didn’t know who to ask.

  5. improve says:

    Great article! This is the type of info that are supposed to be
    shared across the internet. Disgrace on the search engines for now not positioning this
    publish higher! Come on over and discuss with my website
    . Thanks =)

  6. Hi, this weekend is good designed for me, for the reason that this moment i am reading this impressive
    informative post here at my home.

  7. gokarting says:

    We stumbled over here coming from a different page and thought
    I should check things out. I like what I see so now i’m following you.
    Look forward to going over your web page for a second time.

  8. www says:

    These are actually enormous ideas in on the topic of blogging.
    You have touched some good things here. Any way keep up wrinting.

  9. Thanks to my father who stated to me on the topic of this website,
    this web site is in fact awesome.

  10. hey there and thank you for your info – I’ve definitely picked
    up something new from right here. I did however expertise several
    technical issues using this web site, as I experienced to reload the website a lot of times previous to I
    could get it to load properly. I had been wondering if your hosting is
    OK? Not that I’m complaining, but sluggish loading instances times will often affect your placement in google and can damage
    your high quality score if ads and marketing with
    Adwords. Well I am adding this RSS to my e-mail and could look out for
    a lot more of your respective fascinating content.

    Ensure that you update this again very soon.

  11. Hello There. I found your blog using msn. This is an extremely well written article.
    I’ll be sure to bookmark it and return to read more of your useful information. Thanks
    for the post. I’ll definitely return.

  12. I think that everything wrote was very logical.
    But, what about this? suppose you were to create a killer post title?
    I am not saying your information isn’t good., but suppose you added something that grabbed people’s attention? I mean Code Simplicity

  13. jhsnpf.com says:

    Hi there, its nice piece of writing on the topic of media print, we
    all be aware of media is a wonderful source of data.

  14. renovating says:

    Hey there! Somene in my Myspace group shared this website with us so I came to check it out.

    I’m definitely enjoying the information. I’m
    bookmarking and will bee tweeting this to my
    followers! Fantastic blog and amazing style and design.

  15. What’s up, just wanted to say, I loved this article.
    It was inspiring. Keep on posting!

  16. homes says:

    Every weekend i used to go to see this web site, as i want enjoyment, for the reason that this this website conations actually good funny information too.

  17. A mission statement is an organization’s vision translated into written form
    making a leader’s view of the direction and purpose of an organization concreted for everyone’s
    view. The name Norwalk was derived from Norwalk, Ohio, the place where the virus was first identified
    in connection with the outbreak of waterborne disease in one of the town’s primary schools.
    Modern job options online today are exploding
    in growth as more employers look for savings without having to cut quality
    or service, and the most logical option is in the online workforce.

  18. An intriguing discussion is worth comment. I believe
    that you need to write more on this issue, it may not
    be a taboo subject but usually people don’t speak about these subjects.

    To the next! Cheers!!

  19. Hi there, this weekend is good in support of me, as this moment i am reading this enormous informative paragraph
    here at my house.

    Look into my blog: site creator

  20. Great post Ьut ӏ was wondering if you could write а litte morе on this subject?

    I’d be very thankful if үou coսld elaborate a little bit
    mοre. Kudos!

  21. This design is spectacular! You certainly know how to keep a reader
    amused. Between your wit and your videos, I was almost moved to
    start my own blog (well, almost…HaHa!) Fantastic job.
    I really enjoyed what you had to say, and more than that,
    how you presented it. Too cool!

    Feel free to surf to my homepage; how to build online store

  22. web says:

    This post provides clear idea in favor of the new people of blogging, that really how to do blogging.

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>