Comments versus clear code
A comment that says what the code does is often a sign that the code could say it itself. Comments are never run or tested, so they drift: after a few edits, the comment says 30 days while the code says 45.
Before writing a comment that explains what, try:
- renaming a variable so the comment is not needed
- naming a condition, as in
is_adult = age >= 18 - extracting a function named after the comment
Keep comments for what the code cannot say: why a choice was made, where a rule comes from, what a workaround works around. Docstrings tell callers what a function promises.
ADULT_AGE = 18
def can_vote(person):
"""True for registered adults."""
is_adult = person["age"] >= ADULT_AGE
return is_adult and person["registered"]
ada = {"age": 36, "registered": True}
print(can_vote(ada))Your task
Rename process to amount_due(order) with a one-line docstring, and turn its comments into code: extract is_overdue(order) and with_late_fee(amount), and make amount_due call both.
The explanation opens here once every check passes.