Hands-on lab — Day 61: Writing Readable Code

#!/usr/bin/env python3
"""Summarise a list of numeric scores passed as command-line arguments.

This is the readable target of the Day 61 lab: the same behaviour as
``starter/messy.py``, but rewritten in small, named, type-hinted, documented
functions that follow PEP 8. It prints the count, mean, median, minimum,
maximum, population standard deviation, and the percentage of scores at or
above the pass mark.

All input comes from ``sys.argv``, so the tool can be scripted and tested
without a human at the keyboard:

    python3 report.py 70 85 90 55 60
"""
from __future__ import annotations

import sys

# A score at or above this mark counts as "passing". Naming the number gives
# it meaning and one place to change it, instead of a bare 60 in the code.
PASS_MARK = 60.0


def parse_scores(raw_values: list[str]) -> list[float]:
    """Convert the raw command-line strings into a list of floats."""
    return [float(value) for value in raw_values]


def mean(scores: list[float]) -> float:
    """Return the arithmetic mean of a non-empty list of scores."""
    return sum(scores) / len(scores)


def median(scores: list[float]) -> float:
    """Return the middle score, or the mean of the two middle scores."""
    ordered = sorted(scores)
    count = len(ordered)
    middle = count // 2
    if count % 2 == 1:
        return ordered[middle]
    return (ordered[middle - 1] + ordered[middle]) / 2


def population_stdev(scores: list[float], average: float) -> float:
    """Return the population standard deviation around a known average."""
    variance = sum((score - average) ** 2 for score in scores) / len(scores)
    return variance ** 0.5


def passing_rate(scores: list[float]) -> float:
    """Return the percentage of scores at or above PASS_MARK."""
    passing = sum(1 for score in scores if score >= PASS_MARK)
    return 100 * passing / len(scores)


def format_report(scores: list[float]) -> str:
    """Build the multi-line summary report for a non-empty list of scores."""
    average = mean(scores)
    lines = [
        f"count: {len(scores)}",
        f"mean: {average:.2f}",
        f"median: {median(scores):.2f}",
        f"min: {min(scores):.2f}",
        f"max: {max(scores):.2f}",
        f"stdev: {population_stdev(scores, average):.2f}",
        f"passing: {passing_rate(scores):.1f}%",
    ]
    return "\n".join(lines)


def main(argv: list[str]) -> int:
    """Parse scores from argv, print the report, and return an exit code."""
    scores = parse_scores(argv)
    if not scores:
        print("no data")
        return 1
    print(format_report(scores))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

lesson_id: D061
day: 61
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-061-writing-readable-code
  - python3 --version
run_commands:
  - python3 starter/messy.py 70 85 90 55 60
  - python3 examples/report.py 70 85 90 55 60
  - 'diff <(python3 starter/messy.py 70 85 90 55 60) <(python3 examples/report.py 70 85 90 55 60)'
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/messy.py  # optional: reset your refactor'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-13'
executed_on: 'macOS (Apple Silicon), Python 3.14.0, bash tests/run_tests.sh -> 10 checks, 0 failure(s), 2 skipped, exit 0 (unrefactored starter); 14 checks, 0 failure(s), 2 skipped once the starter is refactored'

# Dependencies — Day 061 lab

**Python 3 only. No third-party packages required.**

- `python3` (3.9 or newer; tested on 3.14.0). The reference uses
  `list[float]` type-hint syntax, which reads cleanly on 3.9+. Preinstalled on
  most Linux distributions and installable on macOS; you set this up on Day 43.
- `bash` for the test runner (preinstalled on macOS and Linux).
- Only the Python standard library is used — `sys` and nothing else. There is
  deliberately no `requirements.txt`: refactoring for readability needs no
  libraries at all.

Check your Python is present and new enough:

```bash
python3 --version
```

## Optional style tools (not required)

The lesson introduces a **formatter** (Black) and a **linter** (Ruff, or the
older flake8). They make style automatic, but they are entirely optional here:
the test suite runs with or without them, and simply **skips** their checks
when they are absent. If you want to try them:

```bash
python3 -m pip install black ruff      # optional, one-time
black examples/report.py               # auto-format in place
ruff check examples/report.py          # report style/lint issues
```

If `pip` is restricted on your machine, skip this entirely — everything the
lab asserts works on a plain Python install with nothing downloaded. Windows
users: run the commands inside WSL, or use `python` in place of `python3` if
that is how Python is exposed on your system.

# Refactor THIS file for readability without changing what it does.
# The numbered steps are in starter/refactor-worksheet.md. After every step,
# run  bash tests/run_tests.sh  and confirm the output is still identical.
# It works today; your job is to make it readable, not to change its behaviour.
import sys
def d(a):
    l=[]
    for i in a:
        l.append(float(i))
    if len(l)==0:
        print("no data")
        return 1
    t=0
    for i in l: t=t+i
    m=t/len(l)
    s=sorted(l)
    if len(l)%2==1:
        md=s[len(l)//2]
    else:
        md=(s[len(l)//2-1]+s[len(l)//2])/2
    v=0
    for i in l:
        v=v+(i-m)**2
    v=v/len(l)
    sd=v**0.5
    p=0
    for i in l:
        if i>=60: p=p+1
    print("count: "+str(len(l)))
    print("mean: "+format(m,".2f"))
    print("median: "+format(md,".2f"))
    print("min: "+format(s[0],".2f"))
    print("max: "+format(s[-1],".2f"))
    print("stdev: "+format(sd,".2f"))
    print("passing: "+format(100*p/len(l),".1f")+"%")
    return 0
if __name__=="__main__":
    sys.exit(d(sys.argv[1:]))

# Refactor worksheet — turn `messy.py` into readable code

`starter/messy.py` works: it prints a summary of the numbers you pass it. It
is also hard to read — one giant function called `d`, single-letter variables,
no docstrings, no type hints, a bare magic number, and cramped formatting.
Your job is to make it **readable without changing what it does**. The test
suite is your safety net: `bash tests/run_tests.sh` passes now and must keep
passing after every step.

The golden rule of refactoring: **one small change, then run the tests.** If
they still pass, keep going; if they fail, undo that one change and try again.
Never rename and restructure and retype all at once.

## The five steps (do them in order, testing after each)

1. **Rename for meaning.** Give every name a job title. `d` → `main`;
   `a` → the raw argument strings; `l` → `scores`; `t` → a running `total`;
   `m` → `average`; `s` → `ordered`; `md` → `median`; `sd` → `stdev`;
   `p` → the `passing` count; `i` → `score` (or `value`). Run the tests.

2. **Kill the magic number.** The bare `60` is the pass mark. Add a module
   constant near the top — `PASS_MARK = 60.0` — and use it in the comparison.
   Now the number has a name and one place to change. Run the tests.

3. **Decompose into small functions.** Pull each distinct job out of the giant
   function into its own function: `parse_scores`, `mean`, `median`,
   `population_stdev`, `passing_rate`, and a `format_report` that assembles the
   lines. Leave `main` as a short conductor that parses input, handles the
   empty case, and prints the report. Run the tests after each extraction.

4. **Document and type.** Give the module a top docstring (what the file does)
   and each function a one-line docstring that says **why / what it returns**,
   not a play-by-play of the code. Add type hints to every function signature:
   `def mean(scores: list[float]) -> float:`. Run the tests.

5. **Format and (optionally) lint.** Put blank lines between functions, spaces
   around operators (`t=t+i` → `total += score`), and one statement per line.
   If you have them installed, run `black messy.py` to auto-format and
   `ruff check messy.py` (or `flake8`) to catch leftovers; if you do not, the
   suite skips those checks cleanly. Run the tests one last time.

When you are done, `starter/messy.py` should read like
`examples/report.py` — and `bash tests/run_tests.sh` should report 14 checks,
0 failures (plus the readability checks now applied to your starter too).

## Before/after notes (fill these in)

- **Hardest name to choose, and what you picked:**
- **A function you extracted, and the one job it now does:**
- **One comment you deleted because the code already said it, or one you kept
  because it explained *why*:**
- **Did the tests ever go red mid-refactor? What did you change to fix it?**
- **Final test line (`N checks, 0 failure(s), M skipped.`):**

#!/usr/bin/env bash
# Tests for the Day 061 lab — "Refactor for Readability". Run from the lab
# directory:
#   bash tests/run_tests.sh
#
# The central claim of refactoring is: behaviour does not change, only
# readability does. So these tests characterise the behaviour of the score
# summariser with a fixed golden output, then assert that BOTH the messy
# starter and the clean reference produce exactly that output and the same
# exit codes. They pass before you refactor (messy starter) and after you
# refactor (your cleaned-up starter) — that is the whole point.
#
# The suite also checks the reference for the readability markers this lesson
# teaches (type hints, docstrings, small functions, a named constant), and
# once your starter is refactored it holds it to the same standard.
#
# Finally, if a formatter (Black) or linter (Ruff / flake8) happens to be
# installed, it runs them on the reference as a bonus; if they are not
# installed, those checks are SKIPPED, never failed — the lab must run on a
# plain Python install with nothing extra to download.
#
# No network, non-interactive. Exits 0 only if every non-skipped check passes.
set -u

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ref="${lab_dir}/examples/report.py"
starter="${lab_dir}/starter/messy.py"
failures=0
checks=0
skips=0

# The golden behaviour: for the input below, every correct version of the
# tool must print exactly these seven lines and exit 0.
golden_input=(70 85 90 55 60)
golden_output="count: 5
mean: 72.00
median: 70.00
min: 55.00
max: 90.00
stdev: 13.64
passing: 80.0%"

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

skip() {
  echo "  skip: $1 (tool not installed — optional)"
  skips=$((skips + 1))
}

# behaviour_checks <label-prefix> <script>
# Asserts the golden output + exit 0, the empty-input path, and an even-count
# median — the behaviour that refactoring must preserve.
behaviour_checks() {
  local name="$1" script="$2"
  local out code

  out="$(python3 "${script}" "${golden_input[@]}")"
  code=$?
  if [ "${code}" -eq 0 ] && [ "${out}" = "${golden_output}" ]; then
    check "${name}: golden report matches, exit 0" "yes"
  else
    check "${name}: golden report matches, exit 0" "no"
    echo "    (exit ${code}; output was:)"
    printf '%s\n' "${out}" | sed 's/^/      /'
  fi

  out="$(python3 "${script}" 2>&1)"
  code=$?
  if [ "${code}" -eq 1 ] && [ "${out}" = "no data" ]; then
    check "${name}: empty input prints 'no data', exit 1" "yes"
  else
    check "${name}: empty input prints 'no data', exit 1" "no"
    echo "    (exit ${code}; output: ${out})"
  fi

  # Even count: sorted [55,70,85,90] -> median (70+85)/2 = 77.50.
  out="$(python3 "${script}" 70 85 90 55)"
  if printf '%s\n' "${out}" | grep -qF "median: 77.50"; then
    check "${name}: even-count median is 77.50" "yes"
  else
    check "${name}: even-count median is 77.50" "no"
    echo "    (output: ${out})"
  fi
}

# readability_checks <label-prefix> <script>
# The markers this lesson teaches: type hints, docstrings, several small
# functions, and a named constant instead of a bare magic number.
readability_checks() {
  local name="$1" script="$2"
  grep -q -- '->' "${script}" \
    && check "${name}: uses type hints (->)" "yes" \
    || check "${name}: uses type hints (->)" "no"
  grep -q '"""' "${script}" \
    && check "${name}: has docstrings" "yes" \
    || check "${name}: has docstrings" "no"
  local func_count
  func_count="$(grep -c '^def ' "${script}")"
  if [ "${func_count}" -ge 4 ]; then
    check "${name}: decomposed into >= 4 functions (${func_count})" "yes"
  else
    check "${name}: decomposed into >= 4 functions (${func_count})" "no"
  fi
  if grep -qE '^def [a-z]\(' "${script}"; then
    check "${name}: no single-letter function names" "no"
  else
    check "${name}: no single-letter function names" "yes"
  fi
}

echo "Testing the clean reference (examples/report.py) ..."
behaviour_checks "reference" "${ref}"
readability_checks "reference" "${ref}"

echo "Testing the starter (starter/messy.py) ..."
# Behaviour must hold whether or not the learner has refactored yet.
behaviour_checks "starter" "${starter}"
if grep -qE '^def d\(' "${starter}"; then
  echo "Note: starter/messy.py is not refactored yet — checking behaviour only."
  echo "      Refactor it (see starter/refactor-worksheet.md), then rerun to be"
  echo "      held to the readability standard too."
else
  echo "Starter looks refactored — applying the readability standard to it too."
  readability_checks "starter" "${starter}"
fi

# --- Optional formatter / linter (bonus; never a hard failure) ---
echo "Optional style tools (skipped cleanly if not installed) ..."
if command -v black >/dev/null 2>&1; then
  if black --check --quiet "${ref}" 2>/dev/null; then
    check "black --check: reference is already formatted" "yes"
  else
    check "black --check: reference is already formatted" "no"
    echo "    (run 'black ${ref}' to see the suggested formatting)"
  fi
else
  skip "black"
fi

if command -v ruff >/dev/null 2>&1; then
  if ruff check "${ref}" >/dev/null 2>&1; then
    check "ruff check: reference is clean" "yes"
  else
    check "ruff check: reference is clean" "no"
  fi
elif command -v flake8 >/dev/null 2>&1; then
  if flake8 --max-line-length=100 "${ref}" >/dev/null 2>&1; then
    check "flake8: reference is clean" "yes"
  else
    check "flake8: reference is clean" "no"
  fi
else
  skip "ruff / flake8"
fi

echo
echo "${checks} checks, ${failures} failure(s), ${skips} skipped."
[ "${failures}" -eq 0 ]