Python Comments

Python Comments: Writing Clear Notes and Docstrings

Python comments start with a hash character # and tell the interpreter to ignore the rest of that line. Developers use comments to explain why a decision exists, leave reminders, or temporarily disable lines while debugging.

Good code explains what happens through clear variable and function names. Comments fill the gap when business rules, workarounds, or edge cases are not obvious from syntax alone.

Single-Line and Inline Comments

Place # at the start of a line for a standalone note, or after two spaces at the end of a code line for a brief inline comment.

# Retry failed network calls up to 3 times before alerting
max_retries = 3
timeout_seconds = 10  # API gateway drops connections after 12s

Multi-Line Comments and Docstrings

Python does not have a dedicated /* ... */ multi-line comment syntax. To comment out several lines, prefix each line with # (most editors toggle this with Ctrl+/ or Cmd+/).

Triple-quoted strings ("""...""") placed as the first statement inside a module, class, or function act as docstrings, not comments. Python stores docstrings in the object's __doc__ attribute so tools and help() can inspect them.

def calculate_tax(amount: float, rate: float) -> float:
    """Return sales tax rounded to two decimal places."""
    return round(amount * rate, 2)

print(calculate_tax.__doc__)

Common Mistakes to Avoid

• Repeating what the code already says: Writing # increment counter by 1 above counter += 1 adds noise without value.
• Using triple-quoted strings as mid-function comments: Unassigned string literals still get parsed as string objects and clutter indentation.
• Leaving stale comments after refactoring: An outdated comment misleads future teammates worse than having no comment at all.

Frequently Asked Questions

Does Python execute comments at runtime?

No. The Python parser strips # comments completely before creating bytecode, so comments never slow down your program.

When should I write a docstring instead of a # comment?

Use a docstring at the top of a function, class, or module to describe its public contract, parameters, and return value. Use # comments inside functions for implementation notes.

How do I comment out 20 lines quickly?

Select the lines in your code editor and press Ctrl+/ on Windows/Linux or Cmd+/ on macOS to add or remove # on every selected line.