Readability counts

Software Engineering Principles in Python

Adam Spannbauer

Machine Learning Engineer

The Zen of Python

import this
The Zen of Python, by Tim Peters (abridged)

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
The complex is better than complicated.
Readability counts.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Software Engineering Principles in Python

Descriptive naming

Poor naming

def check(x, y=100):
    return x >= y

Descriptive naming

def is_boiling(temp, boiling_point=100):
    return temp >= boiling_point

Going overboard

def check_if_temperature_is_above_boiling_point(
        temperature_to_check, 
        celsius_water_boiling_point=100):
    return temperature_to_check >= celsius_water_boiling_point
Software Engineering Principles in Python

Keep it simple

The Zen of Python, by Tim Peters (abridged)

Simple is better than complex.
Complex is better than complicated.

  Pizza Slice

Software Engineering Principles in Python

Making a pizza - complex

def make_pizza(ingredients):
    # Make dough
    dough = mix(ingredients['yeast'],
                ingredients['flour'],
                ingredients['water'],
                ingredients['salt'],
                ingredients['shortening'])

    kneaded_dough = knead(dough)
    risen_dough = prove(kneaded_dough)

    # Make sauce
    sauce_base = sautee(ingredients['onion'],
                                ingredients['garlic'],
                                ingredients['olive oil'])

    sauce_mixture = combine(sauce_base,
                            ingredients['tomato_paste'],
                            ingredients['water'],
                            ingredients['spices'])

    sauce = simmer(sauce_mixture)
    ...
Software Engineering Principles in Python

Making a pizza - simple

def make_pizza(ingredients):
    dough = make_dough(ingredients)
    sauce = make_sauce(ingredients)
    assembled_pizza = assemble_pizza(dough, sauce, ingredients)

    return bake(assembled_pizza)
Software Engineering Principles in Python

When to refactor

Poor naming

def check(x, y=100):
    return x >= y

Descriptive naming

def is_boiling(temp, boiling_point=100):
    return temp >= boiling_point

Going overboard

def check_if_temperature_is_above_boiling_point(
        temperature_to_check, 
        celsius_water_boiling_point=100):
    return temperature_to_check >= celsius_water_boiling_point
Software Engineering Principles in Python

Let's Practice

Software Engineering Principles in Python

Preparing Video For Download...