Best Practices Exercise

What follows is some example code from the official Python Tutorial. There is nothing wrong with the syntax. But can you tell what it does and how to use it?

We are going to explore this code and improve it by following programming best practices. In the process, we will gain experience with Notebooks and with running Python functions.

Make a copy of this Notebook in your own Google Drive, and then follow the instructions in the following cells. You will probably want to add more cells as you go along.

def fib(n):
    a, b = 0, 1
    while a < n:
        print(a, ' ')
        a, b = b, a+b
    print()

# Add a command to this cell that executes the function.
# Run it with a few different inputs till you get a good idea of what it does.

fib(20)

fib(100)

Begin Revisions

Copy the original function to the next cell, and add comments that explain…

What is the purpose of the function?
What is the input argument?
What are the variables within the function? (since it isn’t clear from their names)

Testing

When you make changes to the code, be sure and test the output to make sure you didn’t change the operation. You can add the execution command beneath the function and compare the output to what you got before.

There are automated ways to do this; this is called unit testing. It is a critical element of software development. Comparing printed output is fine for now.

# Add your commented code and the execution line to this cell.  Add comments and run it a few more times.

def fib(n):
    # This calculates the Fibonacci Sequence and prints the values.
    # https://www.mathsisfun.com/numbers/fibonacci-sequence.html
    # n is the input target number to end the calculation (integer)

    # assign initial values to current and next variables
    a, b = 0, 1

    # In the Fibonacci Sequence, the current number is the sum of the previous two numbers
    while a < n:
        print(a, ' ')
        # next becomes current. calculate next sum simultaneously
        a, b = b, a+b
    print()

fib(20)

Simplify Code

After adding comments, are there still parts of the code that you don’t understand?

For instance, a, b = b, a+b to Python means “create a tuple and then assign it to two variables with a destructuring assignment”. The advantage of this is that both a and b are assigned new values simultaneously; the orginal value of b will be used for both.

If you don’t know what that means, it might be best reorganize the code in a way to do understand. Feel free to make another copy in the next cell and break those assignments into separate lines. You will need a temporary place to stash the orginal value of b.

# If you want to, add your commented code with the execution line to this cell
# and change the commands to ones you understand.
# Make sure you didn't change the answer!

def fib(n):
    # This calculates the Fibonacci Sequence and prints the values.
    # https://www.mathsisfun.com/numbers/fibonacci-sequence.html
    # n is the input target number to end the calculation (integer)

    # assign initial values to current and next variables
    a = 0
    b = 1

    # In the Fibonacci Sequence, the current number is the sum of the previous two numbers
    while a < n:
        print(a, ' ')
        # next becomes current, and calculate next sum simultaneously
        c = a + b
        a = b
        b = c
    print()

fib(20)

Self Documenting Code

For the next revision, make another copy and change the function and variable names so they are more descriptive.

You can also annotate the function call to specify the type of the argument using typing.

When you are done:

What comments can you remove after you make this change?
Does removing comments make the code easier or harder to read?
- Note: your answer to this depends on your style, and may evolve in time

# Add the next version here.

def fibonacci_sequence(target: int) -> None:
    # This calculates the Fibonacci Sequence and prints the values.
    # https://www.mathsisfun.com/numbers/fibonacci-sequence.html

    # assign initial values to current and next variables
    current = 0
    next = 1

    # print the sequence: the current number is the sum of the two previous
    while current < target:
        print(current, ' ')
        next_sum = current + next
        current = next
        next = next_sum

fibonacci_sequence(20)

Individuality

By this time, your code might look very different from your neighbor’s.

That is completely fine!

But your neighbor should be able to read your code and get what you are doing. Take a minute to compare your Notebook to other people’s.

Epilogue

When I wrote the descriptive code, I realized that the loop is built in terms of current and next, and that conflicts a little with the formal definition of the Fibonacci Sequence. So I’m rewriting again to reflect the math better.

Also, it is possible, and more compact, to write all the numbers on a single line, so do that too.


def fibonacci_sequence(target: int) -> None:
    # This calculates the Fibonacci Sequence and prints the values.
    # https://www.mathsisfun.com/numbers/fibonacci-sequence.html

    # assign initial values
    previous = 0
    current = 1

    # print the sequence
    print(previous, end=' ')
    while current < target:
        print(current, end=' ')
        # the next number is the sum of the two numbers before it
        next_sum = previous + current
        previous = current
        current = next_sum

fibonacci_sequence(20)

0 1 1 2 3 5 8 13