Lesson 8 of 21 · 46 min · UG / professional

Comments, dir, help and docstrings

dir(x) lists names. help(x) prints docs. A docstring is the spec on the function. Comments explain why, not what the names already say.

Library desk

A fee function you can test.

You will be able to

✓ Write comments that explain why a campus number exists
✓ Know dir and help as laptop lookup, not as this sandbox’s Run box
✓ Put a docstring as the first string in a def — the spec a later intern reads

Comments explain why, not what the names already say

pf = 12 does not need a comment that says “pf is twelve”. It needs a comment that says the circular is 2019-04 and the accounts officer still uses 12 until a Gazette change. Comments rot when they repeat the next line. They earn their keep when they record a policy you cannot see in the identifier.

On a laptop, dir(x) lists names on an object and help(x) prints documentation. You will use both in IDLE when you forget whether replace is on str. They are not substitutes for a docstring on a function you wrote — help will show that docstring.

A docstring is the first string in the function

Full Python stores that string as __doc__. This sandbox may not display help(), but it will accept a string as the first line of a def, then your return. That string is the spec: “Hostel late fee in INR for days late.” Callers should not have to read the if/else to learn the unit.

Keep the docstring honest. If the function returns paise, do not write “rupees”. A wrong docstring is worse than none — tests and humans will believe it.

Laptop: dir, help, docstring

def late_fee(days):
    """INR late fee for hostel days overdue."""
    if days <= 0:
        return 0
    return 25

print(late_fee.__doc__)
print(dir(str)[0])
help(len)

Words that matter

Comment: A # line for humans — why, not a restatement of the next identifier.
dir: Laptop: list of names on an object.
help: Laptop: print docs, including your docstring.
Docstring: The first string in a def — the function’s spec.

Common mistakes

Avoid: Commenting every line “add one to i” while leaving the PF circular undocumented.

Do this: Docstring for the contract; comment for the circular; names for the what.

Run it step by step

Each box is a real program. Press Run, change a number, Run again — the output must follow your code.

1. Step 1 — a why-comment next to policy

The number is 12. The comment is the circular, not “this is twelve”.

Python sandboxlesson://workspace

console

Edit the example, press Run, then Build if you want a compile check.

build

Press Build to compile.

2. Step 2 — docstring then a return

First string is the spec. Function still returns 25 for 4 days.

Python sandboxlesson://workspace

console

Edit the example, press Run, then Build if you want a compile check.

build

Press Build to compile.

Example program — Spec on GST, print at the edge

The string is for humans. The return is for tests.

Python sandboxlesson://workspace

console

Edit the example, press Run, then Build if you want a compile check.

build

Press Build to compile.

Your turn — Documented late fee

Put a first-line string spec in late_fee, then return 25 when days is 4. Print so 25 appears.

Python sandboxlesson://workspace

console

Edit the example, press Run, then Build if you want a compile check.

build

Press Build to compile.

Self-assessment

Check your understanding before you mark the lesson complete.

Progress is stored in a browser cookie on this device.