Course A — Software engineering foundations
Unit 8 — Documentation, tests and readability
Self-paced · about 60 minutes · Course A, chapter 4 of 4
Learning objectives
- Write a docstring with
:param,:returnand a>>>example thatdoctestaccepts. - Take a
pytestfile from red to green by reading the assertion it prints. - Rename a function and its parameters so a reader knows what they are for without reading the body.
Lessons
| Lesson | What you leave with |
|---|---|
| 1. Documentation | Comments for the source reader, docstrings for the user, and why the >>> example is a test |
| 2. Unit tests | doctest and pytest, what .. and F. mean, and how to read an AssertionError |
| 3. Readability counts | The Zen of Python, descriptive naming, and refactoring one complex function into simple ones |
| 4. Documentation and tests in practice | :ivar for classes, continuous integration, and the CI badge on this repo |
| 5. Final considerations | Modularity, documentation, testing: the three ideas, and where they show up on Monday |
Checking your answers
Every exercise in notebook.ipynb has the same shape: context, numbered
instructions, a starter that runs as shipped and gives a wrong or incomplete
answer (marked <------ EDIT THIS LINE), the expected output, and a
check(...) cell that prints ✅ or ❌ with the fix named. The last cell,
review("w08"), is the scorecard.
Working with a coding assistant: give it the exercise's context and
instructions, let it edit the marked lines, then run the check cell yourself.
You read the verdict, not the assistant. solutions/notebook.ipynb is the
reference; open it after the check, not before.
Slides
slides.md is a Marp deck. Read it as Markdown, or render it:
npx @marp-team/marp-cli slides.md -o slides.pdf
Previous: Classes in a package · Next: Your first MCP server