Designing Good Functions

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Pure function

A function whose result depends only on its arguments and which changes nothing outside itself.

Side effect

Any change a function makes beyond returning a value: printing, writing a file, changing a global or an argument.

Guard clause

An early if that deals with a special case and returns, so the rest of the code can assume it is not there.

Single responsibility

The idea that a function (or class) should have one reason to change, one job.

In place

Changing the original object instead of making a new one.

Refactor

To change the structure of code without changing what it does.

Sentinel

A special value, often None, that means "nothing was given".

Testable

Easy to check automatically, because inputs and outputs are clear.

1. 1

   Test it with assert

   Add assert add(2, 3) == 5 and assert with_item([1], 2) == [1, 2] at the bottom of the first example. Nothing prints when they pass. Change one expected value to see the AssertionError.

2. 2

   Add an edge case

   Call most_common({}) in the third example. Read the error. Decide what a good function should do for an empty dictionary (return None? raise a clear error? you'll learn how in Phase 7), and write it.

3. 3

   Refactor one more

   Take any function from earlier in the phase and look for: a print that should be a return, a changed argument, a nested if that could return early. Fix one and re-run your checks.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

def add_tax(prices):
    for i in range(len(prices)):
        prices[i] = prices[i] * 1.5
    return prices


original = [100, 200]
taxed = add_tax(original)
print("taxed   :", taxed)
print("original:", original)

1. 1

   One job. Try to describe the function in one short sentence without "and". "Clean the words and count them and print the top one" is three functions. Split it into clean_words, count_words and most_common, and a small outer part that prints. Small functions can be named, tested and reused separately, and bugs have fewer places to hide.

2. 2

   Return, don't print. A function that computes something should return it. Printing is for the outermost layer of the program, the part that talks to a person. If an inner function prints, you cannot reuse its answer, test it with assert, or send it to a file or a web page. A function that returns nothing because it only prints also gives you the None surprises from Topic 5.1.

3. 3

   Pure functions and side effects. A pure function's result depends only on its arguments, and it changes nothing else: add(2, 3) is always 5 and touches nothing. A side effect is any change outside the function: printing, writing a file, changing a global, or changing an object that was passed in. Side effects are sometimes the whole point (saving a file), but they make behaviour harder to predict. Keep the pure logic separate from the parts that have effects, and make the effects obvious in the name (save_report).

4. 4

   Do not surprise the caller by changing their data. Passing a list gives the function the same list, not a copy (Topic 4.9). If the function sorts or edits it in place, the caller's data changes too. Either say so clearly (sort_in_place, returning None, like list.sort) or return a new list and leave the input alone (like sorted). Pick one per function and name it accordingly.

5. 5

   Small signatures. Aim for three or four parameters at most. A long list is a warning: some parameters may belong together (pass a dict, or later a dataclass, Phase 8), the function may do two jobs, or the options should be keyword-only (Topic 5.4). Give optional parts safe defaults (using the None pattern for mutable ones, Topic 5.2).

6. 6

   Early returns (guard clauses). Handle the special cases first and return at once, so the main path is not buried under nested if blocks. Flat code is easier to read than the arrow-shaped nesting. Names matter as much: use a verb for something that does (calculate_total, send_email), a noun or question for something that answers (is_valid, total_price), and no vague names like process or data2.

7. 7

   In AI work these habits are practical rules: a model-callable tool must be a small function with a clear name, simple typed arguments, a docstring that says exactly what it does, and a return value the program can check. Functions that quietly change global state or do five things make agents unpredictable and are hard to test.

• ↔

  Many small functions versus fewer bigger ones. Small functions are testable and nameable, but too much splitting forces the reader to jump around. Split where a piece has its own meaning.

• ↔

  Pure and copying versus in place. Returning new data is safer and simpler to reason about. In-place changes save memory and time for very large data, so numerical libraries use them deliberately (and name them clearly).

• Done when you can describe each of your functions in one sentence without "and".

• Done when you can turn a printing function into a returning one.

• Done when you can tell whether a function changes its arguments, and say so in its name or docstring.

• Done when you can flatten nested conditions with guard clauses and check the results are the same.

• Done when you can list a function's inputs, output and side effects in one breath.