Comments & Documentation
Learn how to leave helpful notes in your code using comments — so future-you (and teammates) always understand what your program is doing and why.
Imagine opening a book you wrote a year ago and finding a single sentence with no context: x = x * 1.08. What does that mean? Is it a tax calculation? A tip? An interest rate? Without a note, you'd have to guess.
Comments solve this problem. They are messages you leave inside your code — for yourself, for teammates, for anyone who reads your program later. Python completely ignores them when running your code. They exist purely for humans.
See it in action
— step through the idea, then dive into the details below.Notes Inside Your Code
A comment is a message you leave in your code for humans to read. Python ignores it completely — it's just there to explain what's going on and why.
#Your First Comment
A comment starts with the # symbol (called a hash or pound sign). Everything after # on that line is ignored by Python. You can put a comment on its own line, or at the end of a line of code.
# This is a comment. Python ignores this line completely.
print("Hello!") # This prints a greeting to the userComments are sticky notes
Think of your code as a recipe and comments as the sticky notes you add to the margins — "use unsalted butter here" or "mom's trick: add vanilla last". The notes don't change the recipe, but they make it a lot easier to follow.
#Full-Line vs Inline Comments
There are two common places to put a comment:
- Full-line comments sit on their own line, above the code they describe.
- Inline comments sit at the end of a line of code, separated by at least two spaces.
Full-line comments are great for explaining a block of logic. Inline comments work well for a quick note on a single line.
# Calculate the total price with 8% sales tax
price = 49.99
tax_rate = 0.08
total = price + (price * tax_rate) # add tax to original price
print(total)#Why Comments Matter
You might be thinking: "I'll just remember what my code does." That's what everyone thinks — and then they come back three weeks later and have no idea what they wrote.
Comments matter because: - Code shows WHAT happens. Comments explain WHY. - Other people (or future-you) will need to understand your decisions. - A well-commented program is a gift to your future self.
Comment the WHY, not the WHAT
A bad comment just restates the code in English: # add 1 to x above x = x + 1 tells you nothing new.
A great comment explains the reason: # start index at 1 because position 0 is reserved for the header row. That's the kind of note that saves hours of confusion.
#Good Comments vs Bad Comments
# BAD: just restates the code
x = x + 1 # add 1 to x
# GOOD: explains WHY
x = x + 1 # skip the first item, which is always a placeholderThe best comments are the ones that would make a future reader say "oh, that's why they did it that way!" If the code already reads clearly on its own, you might not need a comment at all.
#Commenting Out Code
Sometimes you want to temporarily disable a line of code without deleting it — maybe you're testing something, or you're not sure if you'll need it again. You can turn any line into a comment by adding # at the front.
name = "Alice"
print("Hello, " + name)
# print("Goodbye, " + name) # disabled for nowDon't leave dead code forever
Commenting out code is fine while you're experimenting. But if you leave large blocks of commented-out code in your file for weeks, it gets confusing — readers wonder if it's important or just old junk.
As a rule: once you're sure you don't need it, delete it. Your version control system (like Git) keeps the history anyway.
#Multi-Line Comments
Python doesn't have a special multi-line comment syntax. The common approach is simply to start several lines in a row with #.
# This function converts a temperature
# from Celsius to Fahrenheit.
# Formula: F = (C * 9/5) + 32
def celsius_to_fahrenheit(c):
return (c * 9 / 5) + 32
print(celsius_to_fahrenheit(100))#Docstrings: Comments for Functions
Python has a special kind of documentation string called a docstring. You write it using triple quotes (""") right inside a function. It's not technically a comment (Python can read it), but it serves the same purpose: explaining what the function does.
Docstrings are the standard way to document functions, and tools like help() can display them automatically.
def greet(name):
"""Return a friendly greeting for the given name."""
return "Hello, " + name + "!"
print(greet("Maria"))
print(help(greet))Docstrings vs comments
Use # comments for quick notes anywhere in your code. Use """docstrings""" to document what a function does — they follow the def line and describe the function's purpose, inputs, and return value.
Which of these is an example of a GOOD comment?
Key takeaways
- Comments start with `#` and are completely ignored by Python — they're for humans only.
- Comment the WHY, not the WHAT — explain your reasoning, not just what the line does.
- You can disable code temporarily by putting `#` at the start of a line.
- Use `"""triple-quoted docstrings"""` right inside functions to explain what they do.
- Clean up old commented-out code once you're sure it's no longer needed.
What does this code print?
# This line is a comment
print("Python is fun!") # so is this one
# print("This won't show")This code has a bug. What is wrong?
price = 10.00
total = price * 1.08 # apply 8% tax
print(total)
# print("Done!"Complete the code so the function has a proper docstring describing what it does.
def double(n): Return n multiplied by 2. return n * 2 print(double(5))
Put these lines in the right order to print a converted temperature with a descriptive comment.
celsius = 100
fahrenheit = (celsius * 9 / 5) + 32
# Convert Celsius to Fahrenheit
print(fahrenheit)
Below is a short program that calculates a restaurant bill. It works, but it has no comments and a confusing docstring. Your tasks: 1. Add a full-line comment above the tip calculation explaining WHY 18% was chosen. 2. Add an inline comment on the total line explaining what it represents. 3. Replace the placeholder docstring with a real one describing what calculate_bill does.
Try it live — edit the code and hit Run to execute real Python: