Comments in Python
What are comments?
Comments are lines in your code that Python completely ignores when running your program. They exist only for humans to read. You might use them to explain what the code does, leave notes for yourself, or help others understand your code and the decisions you made when writing it. In Python, any text that follows a # (hash) symbol is a comment.
E.g.
# This is a comment - Python skips right over it
print("Hello!") # This is also a comment (after the code)
# The line below prints a greeting
print("Welcome to my app!")
When you run this code, Python only executes the print() statements. Everything after a # symbol is completely ignored.
Hello!
Welcome to my app!
Comment syntax
Lines with the hash # symbol
When a line of text is preceded by a # (hash) symbol, the line is treated as a comment.
E.g.
# This entire line is a comment
print("Hello") # Comment after code
x = 5 # Initialize counter to 5
All text after the # on the same line is a comment.
For multi-line comments, you simply precede each line by the # symbol.
E.g.
# This is a longer explanation
# that spans multiple lines.
# Each line needs its own # symbol.
Docstrings (for documentation)
Triple quotes (“”” or ‘’’) create multi-line strings. While technically not comments (since they can be accessed programatically), they are used for documentation and can replace some kinds of comments, e.g. header comments.
E.g.
"""
This is a docstring.
It documents what a function or file does.
These can be accessed programmatically to generate documentation.
"""
def greet(name):
"""
Greet a person by name.
Args:
name: The person's name
Returns:
A greeting message
"""
return f"Hello, {name}!"
Why use comments?
1) Remember what you did When you return to your code after a week (or even a few hours), comments help you to remember your thinking.
E.g.
# Convert temperature from Celsius to Fahrenheit # Formula: F = (C × 9/5) + 32 fahrenheit = (celsius * 9/5) + 32
2) Explain complicated logic If code is complicated or you have made a decision that you don’t think is obvious, comments help you to explain why you chose to do something a particular way.
E.g.
# We need lowercase comparison so "HELLO" matches "hello" if user_answer.lower() == correct_answer.lower(): print("Correct!")
3) Make a note of something for later You can use special comment tags to mark issues or add future improvements.
TODO: Things you plan to add or improve.
# TODO: Add input validation for negative numbers def calculate_score(points): return points * 10 # TODO: Implement save to file functionality # TODO: Add support for multiple languages
FIXME: Known bugs or problems that need fixing.
# FIXME: This breaks when the list is empty total = sum(scores) / len(scores) # FIXME: Doesn't handle special characters in names user_name = input("Enter name: ")
NOTE: Important information or warnings.
# NOTE: This function assumes input is always positive # NOTE: Must call load_data() before using this function
Use these sparingly - they’re helpful for marking work in progress, but don’t leave them indefinitely. Either fix the issue or remove the comment!
4) Professional practice In a professional context, comments are as essential as the code, since they allow colleagues and collaborators to understand each others’ code and transparently justify the decisions they have taken in their decisions.
Conventions and best practices
✅ DO: Explain why, not what
Good comment explains the reasoning, e.g.
# Convert to lowercase to make comparison case-insensitive
if user_answer.lower() == correct_answer.lower():
score += 1
Add file information at the top, e.g.
# Flashcard Practice Application
# Created by: Alex Ubuntu
# Date: October 27, 2025
# Description: Interactive flashcard app for language learning
✅ DO: Comment complex calculations
Explain the formulae and calculations applied, e.g.
# Calculate percentage, round to 1 decimal place
percentage = round((correct / total) * 100, 1)
# Convert hours to seconds: 60 seconds/min × 60 min/hour
seconds = hours * 60 * 60
✅ DO: Mark TODO and FIXME items (but sparingly and with a time limit)
Use tags to remind yourself to take action later, but try to use these sparingly and aim to resolve them within a day
# TODO: Add error handling for invalid file format
# TODO: Implement spaced repetition algorithm
# FIXME: This breaks when list is empty
❌ DON’T: Just state the obvious or just repeat the code (unless you’re learning)
E.g.
# Print hello
print("hello")
# Add 1 to x
x = x + 1
# Create a variable called name with value "Alice"
name = "Alice"
# Check if user answer equals correct answer in lowercase
if user_answer.lower() == correct_answer.lower():
score += 1
In a professional context, these comments add little value since the code is self-explanatory. Instead you should use comments to explain why you’re doing something.
Having said this, when you are learning, you may find such explanations of the code useful, in which case you should include them. During the course you should use your own judgement to determine which comments are and are not useful to include.
❌ DON’T: Leave outdated comments
E.g.
# TODO: Fix this later (written 6 months ago, still not fixed)
# This function returns the sum (it doesn't anymore - now returns average)
def calculate(a, b):
return (a + b) / 2
You should keep comments up-to-date when you change the code, or delete them if they are no longer relevant.
❌ DON’T: Use comments to “save” old code
E.g.
# result = x + y # Old way
# result = x * 2 # Tried this, didn't work
result = x * y + 5 # Current version
Git already allows you to track changes so there is really no need to keep old code, which will only make it more difficult to work with. Instead you should simply delete old code and just keep the current version.