Code Layout—Readability Counts

by Nigel George

One of the founding principles behind Python’s design is that code is read much more often than it’s written. Once a piece of code is written, it often passes through many hands—other developers, documentation authors, auditors and testers. Experienced programmers will also tell you that being able to understand your own code many months, or even years, after you wrote it is extremely important. Under this guiding principle, Python was designed to mimic natural written English as much as possible. One of these design choices was to use white-space as a delimiter, rather than braces ({}), or the BEGIN\END type statements used by other languages. A delimiter is something that defines the beginning or the end of a block of related text. Consider the following:

# Kate's Awesome Nachos

1.	Collect Ingredients:
    a.	Large bag of corn chips
    b.	Can of refried beans (preferably chili)
    c.	Jar of salsa (not hot!)
    d.	Grated cheese
    e.	Guacamole
2.	Prepare Nachos:
    a.	Tip bag of corn chips in oven dish
    b.	Spread refried beans over corn chips
    c.	Pour on jar of salsa
    d.	Top with cheese
3.	Cook in oven for 20 mins
4.	Serve with guacamole

We can easily understand each step of this simple (but delicious!) recipe because it’s formatted in a way that all English speakers can understand— relevant information is grouped together in sentences and paragraphs and indentation is used so we can differentiate between Step 1, collecting the ingredients and Step 2, preparation of the nachos.

Python treats whitespace the same way, for example the ingredients written as a Python list may look like:

ingredients = [ 
    "corn chips", 
    "refried beans", 
    "grated cheese", 

You will notice that Python lists use brackets ([]) as a delimiter, with the indentation and surrounding whitespace clearly differentiating where the list starts and ends. (More on lists shortly.) Functions for preparing and cooking the nachos might be written like this:

def prepare_nachos(ingredients): nachos = ""
    for ingredient in ingredients[:4]: 

def cook_nachos(nachos):
# cook in oven for 20mins

Now this is a rather silly example, but I bet that you found it easy to follow—even without quite understanding Python syntax. Our list of ingredients is broken up into one ingredient per line to create our ingredients list, and we have used indentation to differentiate between the two Python functions (prepare_nachos and cook_nachos) and the code that belongs to each function. Here are some real examples that you will see later in the course:

# A list from the file: 


# A function from

def index(request, pagename): 
    pagename = '/' + pagename
    pg = Page.objects.get(permalink=pagename) 
    context = {
        'title': pg.title, 
        'content': pg.bodytext,
        'last_updated': pg.update_date, 
        'page_list': Page.objects.all(),
    return render(request, 'pages/page.html', context)

I don’t expect you to understand this code right now, but as you can see, the layout of the code makes it easy to follow without you necessarily understanding exactly what’s going on.

Indentation and intuitive use of whitespace are not the only stylistic conventions designed to make Python code more readable. Python has a complete style guide called PEP8. I strongly encourage you to read this document, absorb what it has to say any try to follow PEP8’s recommendations in all of your programming.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}