Skip to content
Open DegreeOpen Degree

Write functions with clear signatures

I can write a Python function with parameters, defaults and a return value, document what it does, and call it with positional and keyword arguments.

Domain
Python Programming
Level
foundation
Status
draft · v0.1.0
Also called
Python functions, Function arguments, Keyword arguments, Docstrings
License
CC BY-SA 4.0

Learn first

Learn it

Scope

Writing a function someone else can call without reading its body, and calling one you did not write.

In scope: parameters and arguments, defaults, return values, docstrings, and the calling conventions Python offers. Out of scope: decorators, closures and type annotations, which have their own place later.

A signature is a promise

Everything a caller needs should be visible in the first line and the docstring: what goes in, what comes out, and what the function is for. A function whose behaviour depends on a global, or which returns different types depending on its input, has broken that promise even if it works.

Return something rather than printing, unless printing is the point. A function that prints can only be used one way; a function that returns can be printed, stored, tested or combined.

A function with no return returns None. That is a real value, and forgetting it is the source of the classic bug where result is mysteriously None two lines later.

Calling conventions, in the order they bite

  • Positional arguments are matched by order. Fine for one or two, unreadable for five.
  • Keyword arguments are matched by name, so send(retry=3) reads at the call site.
  • Defaults make an argument optional — and are evaluated once, when the function is defined. A mutable default (def f(items=[])) is shared by every call that omits it, which is the most famous trap in the language. Use None and create the list inside.
  • *args and **kwargs collect the rest. Useful for wrappers; a poor substitute for naming the arguments you actually take.

Common misconceptions

  • “Printing and returning are much the same.” A print is a side effect a caller cannot use.
  • “A default is evaluated each call.” It is evaluated once at definition, which is why mutable defaults leak state between calls.
  • “More arguments means more flexible.” Past three or four, a function is usually two functions, or it wants a small object.
  • “Docstrings are for documentation generators.” They are for the person calling it in six months, usually you.

Notes for teachers

Take a working script with three near-identical blocks and have learners extract one function that serves all three. The argument list they end up with is the lesson: what genuinely varies, and what they were tempted to pass but did not need.

Then hand them the mutable-default trap as a puzzle before explaining it. Being surprised once fixes it permanently.

Resources

ResourceKindCostProvider
The Python Tutorial: control flow and defining functionsreadingfreePython Software Foundation
Automate the Boring Stuff, chapter 3: functionsreadingfreeAl Sweigart
CS50P, week 2: loopsvideofreeHarvard University

Courses that include it

draft

Python for a Coding Assessment

A refresher path through the Python graph for someone who has written Python before and has an assessment coming: run and read, rebuild the core, then work the way an assessment expects.

Prove it

Evidence of mastery

  • Turns a repeated block of a script into a function with a name that says what it does, and the script still runs.
  • Writes a function with a default argument and calls it both with and without that argument.
  • Explains what a function returns when it has no return statement, and what that means for the caller.
  • Reads an unfamiliar signature, including keyword-only arguments and `*args`/`**kwargs`, and calls it correctly the first time.

Assessments that measure it

project

Python Take-Home Task

A timed take-home in the shape real hiring uses: read messy data, compute a result, test it, and hand over a repository someone else can run.

Credentials that include it

draft

Python Problem Solving

The holder can take an unfamiliar problem, write a tested Python solution someone else can run, and explain what it costs.

What learners show

Nothing to show yet. The publisher last published on 2026-09-20, and no aggregate for this outcome has reached the 50 learners a number needs. Open Degree does not track learners. About learner evidence.

What comes next