Comments in Python

Analogy categoryAnalogies

1. Introduction

Comments are lines in source code that the Python interpreter ignores when running a program. They exist purely for human readers — to explain what a piece of code does, why a decision was made, or to temporarily disable a line during debugging.

🏏

Cricket analogy: A coach's handwritten note in the margin of a scoring sheet — 'switched bowler here because pitch was turning' — is never read by the scoreboard itself, just like a Python comment the interpreter ignores but a human reads to understand the decision.

Good commenting makes code easier to maintain and understand, both for other developers and for yourself when you revisit code months later. Python supports single-line comments, a common idiom for multi-line comments, and docstrings for documenting modules, classes, and functions.

🏏

Cricket analogy: A well-annotated scouting report — quick sideline notes during a match plus a full pre-series dossier — helps a coach months later, just as Python offers quick single-line # comments plus fuller docstrings for modules, classes, and functions.

2. Syntax

python

# This is a single-line comment
x = 5  # inline comment after code

# Multiple
# single-line comments
# stacked together

"""
This is a docstring-style
multi-line string, often used
as a block comment.
"""

3. Explanation

A single-line comment starts with # and extends to the end of the line; everything after # on that line is ignored by the interpreter. Python has no dedicated multi-line comment syntax like /* ... */; the common convention is to stack multiple # lines, or to use a triple-quoted string as a 'block comment' when it is not assigned to anything.

🏏

Cricket analogy: A single sideline shout of 'watch the short ball!' only covers that one delivery, like a # comment ending at the line; for a longer briefing, a coach either gives several short shouts in a row or one full unassigned team-talk speech, like stacked # lines or a triple-quoted block.

A docstring is a special triple-quoted string that appears as the very first statement inside a module, class, or function. Unlike an ordinary comment, a docstring is stored by Python and can be accessed at runtime through the object's __doc__ attribute or the help() function, making it useful for auto-generated documentation.

🏏

Cricket analogy: A player's official bio card printed in the match program — accessible to anyone who looks it up — is like a docstring stored via __doc__, unlike a coach's private sideline note that vanishes after the match, just like an ordinary comment.

Use inline comments sparingly and only when they add information not obvious from the code itself; over-commenting obvious code (e.g., x = 5 # set x to 5) adds noise rather than clarity.

Common misconception: a triple-quoted string that is not assigned or used as the first statement of a function/class is not truly a 'comment' — it is still a string literal object that Python evaluates and then discards. It works as a comment in practice, but it is not skipped the way a # line is, and it is not attached as a docstring unless it is the first statement in its scope.

4. Example

python

# This is a single-line comment
print("Hello")  # inline comment

"""
This is a multi-line string
often used as a comment block
"""

def greet():
    """This is a docstring for the greet function."""
    print("Hi there!")

greet()
print(greet.__doc__)

5. Output

text

Hello
Hi there!
This is a docstring for the greet function.

6. Key Takeaways

Single-line comments start with # and run to the end of the line.
Python has no dedicated multi-line comment syntax; stacked # lines are the common idiom.
A triple-quoted string as the first statement in a module/class/function becomes a docstring.
Docstrings are accessible at runtime via __doc__ or help().
Comments should explain 'why', not restate obvious 'what'.
Unassigned triple-quoted strings are still evaluated as string objects, not truly skipped like # comments.