Courses/Python Mastery/Module 2: The Building Blocks (Tokens & Syntax)
Module 2 · Lesson 410 minBeginner

Comments & Docstrings

Lesson goal
Write notes in your code the right way — # comments vs docstrings, and why future-you will thank you.

Comments & Docstrings

Code tells the computer what to do. Comments tell humans why. Both matter — and the difference between them confuses beginners constantly, so let's settle it in one lesson.

Comments: the # symbol

Anything after a # is ignored by Python completely — it exists only for human eyes:

code
# Calculate the final price with 18% tax
price = 100
final = price * 1.18     # multiply, don't add — tax applies to the base
print(final)             # 118.0

Three legitimate uses:

  • The why, not the what. price = price * 1.18 already says *what* happens; the comment explains *why* 1.18 (tax rate). Code says what; comments say why.
  • TODO notes — # TODO: handle empty cart marks work you know is pending.
  • Temporarily disabling code — put # in front of a line to switch it off without deleting:
    • code
    # print("debug: price is", price)     # switched off, not deleted

    This is called "commenting out" and you'll use it constantly while debugging.

    The anti-pattern: commenting the obvious

    code
    # increment count by 1        ← the code already says this!
count = count + 1

    Bad comments repeat the code. Good comments explain the *reasoning the code can't express*:

    code
    # API rate-limits us to 1 request per second; sleep avoids the 429 error
time.sleep(1)

    Rule: if you remove the comment and nothing is lost, it was a bad comment.

    Docstrings: documentation that Python reads

    A docstring is a triple-quoted string placed first inside a function or file. Unlike comments, Python *keeps* docstrings and can display them:

    code
    def calculate_bmi(weight, height):
    """Return the BMI from weight (kg) and height (meters)."""
    return weight / (height ** 2)

    The magic: Python can show you this documentation on demand:

    code
    help(calculate_bmi)

    Output:

    code
    Help on function calculate_bmi:

calculate_bmi(weight, height)
    Return the BMI from weight (kg) and height (meters).

    Every professional Python function has a docstring — it's how libraries document themselves. When you ran help(len) and got real documentation, you were reading a docstring written by Python's developers.

    Comment vs docstring — the one-line difference

    Comment #Docstring """..."""
    Read byHumans onlyHumans and Python
    LocationAnywhereFirst line inside functions/classes/files
    PurposeExplain reasoningDocument usage (feeds help())

    Common Errors & Fixes

  • `SyntaxError: unterminated string literal` — a docstring opened with """ but not closed with """. They come in threes, both sides.
  • Commented-out code that still "runs" — check for stray text after a # that wrapped from the previous line; every line needs its own #.
  • Docstring has no effect — it must be the *first* statement inside the function; a comment or blank line before it displaces it.

    • ✅ Checkpoint

  • What's the symbol for a comment, and what does Python do with it? *(# — ignores everything after it)*
  • Which feeds help() — a comment or a docstring? *(Docstring)*
  • Rewrite the bad comment: # set x to 5 above x = 5. *(Delete it — it repeats the code. If there was a reason, state the reason.)*

    • Next: indentation — the one Python rule that surprises every newcomer, explained so it never surprises you again.