Search⌘ K
AI Features
Home
Courses
Learn Python 3: Comprehensive Programming Guide

Comments and Documentation

Explore how Python comments and docstrings help you communicate code intent and purpose clearly. Learn to write meaningful annotations that explain why code is written rather than what it does, ensuring your programs remain understandable and maintainable as they grow.

We'll cover the following...

Coding is a communication skill. While we write code for computers to execute, we write documentation for humans to read. In professional environments, you will spend more time reading and maintaining existing code than writing brand-new scripts. If code explains how a program works, documentation explains why it exists. We use comments to leave notes for our teammates (and for our future selves), ensuring that complex logic remains understandable long after it is written.

The single-line comment

In Python, any text following a hash mark (#) on a line is ignored by the interpreter. This is a comment. We use comments to annotate our code with context that isn't obvious from the syntax alone.

We can place comments on separate lines to describe the block of code that follows, or inline at the end of a statement to add a brief note about a specific line.

Python
# This is a standalone comment ignored by Python interpreter
print("System starting...")  # This is an inline comment
# print("This line will not execute.") 
print("System ready.")

  • Line 1: Standalone comments that explain the general behavior or intent.

  • Line 2: An inline comment providing context for the specific statement on the same line.

  • Line 5: A "commented out" line of code. The interpreter skips it, which is useful for temporarily disabling logic during testing.

Multi-line blocks

Sometimes a single line isn't enough to explain a complex decision or a business rule. Python does not have a specific "block comment" syntax (like /* ... */ in C or Java). Instead, idiomatic Python uses consecutive single-line comments to create a block of text.

Python
# The following section simulates a retry logic
# We print a message to the user, then simulate
# a waiting period before the next attempt
# Note: In a real app, we would check network status here
print("Attempting connection...")
print("Retrying in 3 seconds...")

  • Lines 1–4: A block of consecutive comments describing the intent of the upcoming code block.

  • Lines 6–7: The actual executable code corresponding to the explanation.

While it is technically possible to use a multi-line string (triple quotes) as a comment if it is not assigned to a variable, this is not standard practice for general notes. We reserve strings for documentation as discussed below and use hash marks for implementation comments.

Documentation strings (docstrings)

Python has a special feature called a docstring (documentation string) used to document modules, functions, and classes. Unlike regular comments, which are discarded by the interpreter, docstrings are preserved at runtime. This allows tools, IDEs, and the help() function to read your documentation and display it to other developers.

We define a docstring by using triple double-quotes (""") as the very first statement in a file (or inside a function/class).

Python
"""
Report Generator Script
This script simulates the generation of a daily status report
It demonstrates standard output formatting
"""
# We can technically see the docstring internally, though we rarely print it directly
print(__doc__)

  • Lines 1–6: The module docstring. It sits at the very top of the file and describes what the entire script does.

  • Line 9: We are accessing the special __doc__ keyword. Python automatically stores the docstring in this variable, proving that the text is preserved by the program.

Writing effective comments

The quality of your comments matters as much as the quality of your code. Beginners often fall into the trap of commenting on what the code is doing, which is redundant because the code already shows that.

Effective comments explain why something is done or provide context that the code cannot express.

  • Bad comment: It repeats the code. For example:
    print("<something>") # prints the text
  • Good comment: It explains the business rule or intent:
    print("<something>") # we greet the user to confirm the system is active

We strive for code that is self-explanatory, using comments only when the logic implies a question that the code itself cannot answer.

We have explored how to annotate our code using # for implementation details and """ for high-level documentation. We learned that comments should explain the why, not the what, and that docstrings are a functional part of Python that tools can read. As we build more complex programs, these habits will ensure our work remains readable and professional.