Stijlgids

Programmacode is bij voorkeur goed leesbaar, niet alleen voor jezelf, maar ook voor een ander met wie je samenwerkt. Eerder hebben we al kort een aantal richtlijnen genoemd voor het gebruiken van commentaar bij stukjes code. Maar er zijn meer aspecten, die je hieronder kunt vinden.

De gids is momenteel in het Engels. Heb je hulp nodig bij het begrijpen, vraag dan gerust!


As readers of your assignments we’ll notice all too soon if it is well-readable. It influences how quickly we are able to understand the meaning of the program.

Not only in class but also in practice it proves to be convenient to write well-readable code. For the sake of someone else having to read your code, and definitely for yourself, trying to debug the code after a week or so.

There is not one correct way to write code. Still, there’s a lot you can do wrong (or should we say: unreadable). In this course, we require you to adhere to the rules in this style guide. That said, you are free to change some rules, provided that you apply the rules consistently and annotate atop your code what rule you have changed.

Comments

Too much commenting is wrong. Too little commenting is also wrong! So how do you do this right? Well, as a rule of thumb, try to divide your code into small blocks of a few lines each, and add one line of comments above it.

What should you write in your comments? Try to answer relevant questions:

Example 1

Variables are often self-explanatory because of their well-chosen name. Still, names can get long if you want to be precise, so a comment can explain a bit more:

# compute student's average
average = sum / QUIZZES + 0.5

(So now we know it is not just an average, but the average grade of a student.)

Example 2

In the middle of your code you shouldn’t write whole sentences, but rather small annotations. Even so, they should be properly formatted in your language of choice, including readable spacing.

Don’t do this:

#compute student's average

But do it like this:

# compute student's average

Example 3

Atop your Python source code, add a comment block summarizing the goal of the program (what does it do for the user?), and preferably your name.

# Name: Jane Lee
# Collaborators: John Doe
#
# This program calculates the average values of a series
# of numbers input by the user.

Example 4

Have another look at the summary in the comments of Example 3. The summary is fairly long and does not fit a comfortable line’s length. People read most comfortably when lines are about 45-90 characters in length (this also applies to books and other texts!).

In order to split longer comments into multiple lines, just add another line starting with a #.

Indentation

Indentation means adding white space to the very start of a line, in order to show structure. In most programming languages, this is a convention to improve consistency and readability. In Python, indentation is compulsory, or your programs will not work!

def sum(x, y):
    result = x + y
    return result

Tabs and spaces

It is very important to use either tabs or spaces for indentation. Do not mix tabs and spaces. Other programmers will not like it at all.

Say you have your computer set at: 1 tab equals 4 spaces. Another programmer can change this setting to 8 spaces. But now there’s a severe problem in understanding the program:

def sum(x, y):
    result = x + y     # vier spaties
        return result  # 1 tab is hier 8 spaties geworden

Luckily for you, in Python you can’t really make this mistake inadvertently, because Python will complain hard when you do this.

Compulsory (compulsive) indentation

In Python it is quite easy to know when you should indent a line. After a line that ends in a : (colon), all dependent lines should be indented.

# This function consists of 4 lines of code and
# 2 lines of commenting.
def sum(arrayOfNumbers):
    result = 0
    # This for loop contains exactly 1 line that is repeated.
    # The next line after is unindented.
    for number in arrayOfNumbers:
        result = result + number
    return result

Naming stuff

Lots of elements in your Python programs will have a name: mostly functions and variables.

Functions

Function names may be as long as you want. You should separate English words with underscores like this:

def user_average_this_year():
    ...

Variables

Variable names are preferably a tad shorter than function names, because they are used more frequently. Keep those names to one or two words.

There is no good reason to shorten names (unless you are an extremely bad typist). It is allowed, however, to use symbols derived from the domain of your program, like mathematics.

d = 0.002                   # d is for "delta"
remaining_pension -= 2000   # very good name

White space for readability

Just as in other media that revolve around text, blank lines and white space may be added to increase clarity of structure, and thus, readability.

Blank lines

When you split some code into blocks, as described above in “Comments”, add a blank line atop each comment in order to split the code into logical blocks.

Here’s three very small blocks of code, each responsible for a particular function of the program:

number = input("Please enter a number: ")
while number < 0:
	number = input("Please enter a *positive* number: ")

# calculations: uses a complex loop to handle special cases
while(number > 0):
	number -= 1
if number == 0:
	number += 1

# output: might not print zero (e.g., if user put in a float)
print user_input

Spaces around operators

Operators are compactly named functions, like +, ==, % and ?. You should ornament your expressions with spaces in order to make them easy to read.

Simply add one space before, and one space after each operator:

i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)