Writing Code Poetry — Readability

Good code should be as readable as prose.

Most engineers don’t realize that through the journey of becoming a software developer, you also become a writer. You develop your own characteristic vocabulary, punctuation patterns, and most importantly your own storytelling style.

You can ask 5 writers to tell the same story and the outcome will be different every single time. Go ahead and ask 5 developers to write the same algorithm and I guarantee you their code will be different in more than one way.

This is because our code is a reflection of our thoughts and the process we go through to arrive to them. This process is different for each one of us which in turn results in completely different code. This is precisely why we need to tell our stories in a way that allows others to easily understand them, or what we as developers refer to as writing readable code.

Although the guidelines may be slightly different for every language, the underlying principle is the same: write code other people can read.

The following are some simple guidelines I’ve put together that should help you write poetry in your favorite programming language.

1. Strive for self-documenting code.

Write code that describes itself so that documenting it isn’t necessary.

func configureDeliveryButtonLayout() {…} // clear & concise/**
  Configures the delivery button’s layout.
*/
func configureDeliveryButton() {…} // clear only when reading doc, not so concise

2. Choose names wisely.

Use names that are concise but explicit about what they represent.

var menuItemCount: Int; // got it
var counter: Int; // huh? counter for, what?

3. Always assume you’re writing code for someone else.

Even if it isn’t always the case, this is a good rule of thumb to write code that someone else would be delighted to read, or even yourself a few months from now.

4. Adhere to your language’s styling guide & naming conventions.

Learn and follow your language’s style guide, naming conventions and best practices. For instance in my case, I visit this swift style guide pretty frequently for inspiration.

5. Avoid cryptic abbreviations

Sometimes the temptation rises to abbreviate names in order to save space and/or keystrokes. Only do so when there is no room for ambiguity.

configureOrderMgr(); // clear
configureSV(); // configure scrollView? maybe? signup view?

6. Be Consistent with Indentation

As insignificant as they seem, indentation and spacing are 2 of the most influential factors in pretty, readable code. Make sure your IDE’s configuration is consistent on your different machines and coordinate with fellow developers on such settings.

var a = “abcd”;
  var b = “ef”;// i'm your code & i love you. please no do this :(
var c = “abc”;

7. Use new lines to group related groups of code

// write this:
var containerView = UIView();
containerView.backgroundColor = UIColor.greenColor();
self.view.addSubview(containerView);
var childView = UIView();
childView.backgroundColor = UIColor.whiteColor();
containerView.addSubview(childView)// instead of this:
var containerView = UIView();
containerView.backgroundColor = UIColor.greenColor();
self.view.addSubview(containerView);
var childView = UIView();
childView.backgroundColor = UIColor.whiteColor();
containerView.addSubview(childView);

8. Attack complexity by decomposing it

One of the reasons code fragments are difficult to read is because of their complexity level. This is specially true with authentication pieces or involved calculations.

The best way to mitigate complexity is by decomposing it into more manageable pieces. This may make your code a bit longer, but at the same time it will make it more readable and manageable.

let viewLength = self.view.frame.size.width - (self.imageView.frame.size.width - ViewPadding) - (self.deliveryButton.frame.size.width - ViewPadding);// how about this?
let imageViewWidth = self.imageView.frame.size.width - ViewPadding;
let deliveryButtonWidth = self.deliveryButton.frame.size.width - ViewPadding;
let viewLength = self.view.frame.size.width - imageViewWidth - deliveryButtonWidth;

9. Exploit Return Statements

Once a function arrives to a return statement, you as a developer stop reading. Keeping this in mind can help you write functions that don’t need to be read in their entirety by placing return statements in your logic’s inflection points.

func canPlaceOrders() {
        var canOrder = true;
        if(!restaurantIsOpen) {
        canOrder = false;
    } else if(!restaurantIsNear) {
        canOrder = false;
    }
        return canOrder;
}// easier to read, isn't it?
func canPlaceOrders() {
        if(!restaurantIsOpen) {
        return false;
    } if(!restaurantIsNear) {
        return false;
    }
        return true;
}

10. Document only when needed

Although documenting your work is a great practice, overdoing it is not. I find that some engineers document when it is not needed. This increases the amount of text we have to read and the amount of code we have to maintain.

Some docs just don’t add any value and hence should be left out:

/** 
  :returns: The tip
*/
func getTip() -> Double {...}
func getTip() -> Double {...} // ahh, so much shorter :)