Comments and Documentation
Overview
Writing readable code is just as important as writing correct code. Learn how to use comments and docstrings effectively to explain your logic, making your programs easier to understand and maintain.
What You Will Learn in This Lesson
By the end of this lesson, you will know:
- What comments are and why they matter: Understand how comments help you and others understand code.
- How to write single-line comments: Use
#to add notes to your code. - How to write multi-line comments: Document larger sections of code.
- Best practices for commenting: Learn when and how to write helpful comments.
Why Comments Matter
Code tells the computer what to do, but comments tell humans why you wrote it that way. Good comments make your code easier to understand, debug, and maintain. They're especially helpful when you come back to your code weeks or months later.
Step 1: What Are Comments?
Comments are notes you write in your code that Python ignores. They're for humans to read, not for the computer to execute. Comments help explain what your code does and why you wrote it that way.
age = 25
next_year = age + 1
print(next_year)# Store the current age
age = 25
# Calculate age for next year
next_year = age + 1
# Display the result
print(next_year)Key Concept: Comments don't affect how your program runs. Python completely ignores them. They're purely for documentation and explanation. This means you can write anything you want in comments without breaking your code.
Step 2: Single-Line Comments
The most common type of comment is the single-line comment. You create it by putting a # symbol at the beginning of a line. Everything after the # on that line is ignored by Python.
# This is a comment
age = 25 # This comment is at the end of a line
# print("This won't run") # Commented-out codeFull-Line Comments
Put # at the start of a line to make the entire line a comment. Use this to explain what a section of code does.
# Calculate the total price
total = price * quantityInline Comments
Put # after code on the same line. Use this to explain a specific line.
age = 25 # Current age in yearsCommenting Out Code
Put # before code to temporarily disable it. This is useful for debugging or testing different approaches.
# print("Old code")
print("New code")Mini Practice #1: Adding Comments
Try It YourselfTry adding comments to explain what this code does:
Notice: The comment doesn't affect the output. Python runs the code but ignores the comment. Comments help explain what the code does.
Step 3: Multi-Line Comments
For longer explanations, you can write multi-line comments. Python doesn't have a built-in multi-line comment syntax, but you can use multiple single-line comments or triple-quoted strings.
# This is a multi-line comment
# Each line starts with #
# Python ignores all of these lines
# This is useful for longer explanations"""
This is a multi-line string
that Python can use as a comment
if it's not assigned to a variable.
This is called a docstring.
"""When to Use Each Method
- Single-line comments (
#): Use for short explanations or notes - Multi-line comments (
#on each line): Use for longer explanations - Triple-quoted strings (
"""): Use for function documentation (we'll learn about functions later)
Step 4: Best Practices for Comments
Good comments make code easier to understand. Bad comments can be confusing or unnecessary. Here are guidelines for writing helpful comments:
✅ Do: Explain Why
Good comments explain why you wrote code a certain way, not just what it does. The code itself shows what it does.
# Use int() because input() returns a string
age = int(input("Age: "))❌ Don't: State the Obvious
Avoid comments that just repeat what the code obviously does. These add clutter without value.
# Set age to 25
age = 25 # This is obvious!# Convert string to int because input() always returns strings
# We need a number to perform calculations
user_age = int(input("Enter your age: "))# This is a variable called user_age
# It gets input from the user
# Then converts it to an integer
user_age = int(input("Enter your age: "))Golden Rule: Write comments that explain things that aren't obvious from reading the code. If someone can understand what your code does just by reading it, you don't need a comment. If there's a reason why you wrote it that way, or if it's doing something complex, add a comment.
Mini Practice #2: Writing Good Comments
Try It YourselfAdd helpful comments to explain why this code does what it does:
Notice: The comments explain why each step is necessary, not just what it does. This makes the code much easier to understand.
Step 5: When to Comment
Knowing when to add comments is as important as knowing how. Here are situations where comments are especially helpful:
Complex Logic
When your code does something complicated or non-obvious, add a comment explaining the logic.
# Calculate discount: 10% off if over $100
if total > 100:
discount = total * 0.10Non-Obvious Decisions
When you made a specific choice that might not be obvious, explain why.
# Use float instead of int to handle decimals
price = float(input("Price: "))Section Headers
Use comments to organize your code into logical sections.
# ===== USER INPUT SECTION =====
# Get user information
name = input("Name: ")
age = int(input("Age: "))End-of-Lesson Exercises
Exercise 1: Add Comments
Write code that calculates the area of a circle (radius = 5). Add comments explaining each step. Use the formula: area = π × radius² (use 3.14 for π).
Add comments that explain why you're doing each calculation, not just what the code does.
Exercise 2: Comment Your Code
Write code that gets a price, adds 8% tax, and prints the total. Add helpful comments explaining why each step is necessary.
Remember: comments should explain why, not just what.