Python Comments
Python comments are text annotations in your code that the Python interpreter ignores during execution. These comments serve as explanations, reminders, or documentation for other developers (including your future self) who read your code. Python comments help explain complex logic, provide context for variables and functions, and make your codebase more maintainable.
Types of Python Comments
Single-Line Comments in Python
Single-line Python comments start with the hash symbol (#) and continue until the end of the line. Everything after the # symbol is treated as a comment and ignored by the Python interpreter.
# This is a single-line comment
print("Hello, World!") # This comment explains what this line does
You can place single-line Python comments at the beginning of a line or at the end of a code statement. The flexibility of single-line comments makes them perfect for quick explanations and annotations.
Multi-Line Comments in Python
While Python doesn’t have a specific multi-line comment syntax like some other languages, you can create multi-line comments using several approaches:
Method 1: Multiple single-line comments
# This is a multi-line comment
# that spans across multiple lines
# Each line starts with a hash symbol
Method 2: Triple quotes (docstrings)
"""
This is a multi-line comment
using triple quotes
It can span multiple lines
"""
Method 3: Triple single quotes
'''
Another way to create
multi-line comments
using triple single quotes
'''
Inline Comments in Python
Inline Python comments appear on the same line as code statements. They provide immediate context for specific operations or variables.
age = 25 # User's age in years
total_price = price * 1.08 # Add 8% tax to the price
When writing inline Python comments, maintain at least two spaces between your code and the comment for better readability.
Python Comment Syntax Rules
Understanding Python comment syntax is crucial for effective code documentation:
- Hash symbol placement: The
#symbol must precede any comment text - Whitespace handling: Python comments can have spaces before the
#symbol - Case sensitivity: Python comments are case-sensitive like the rest of Python code
- Special characters: You can use any characters in Python comments, including Unicode
- Line termination: Single-line comments end at the line break
# Indented comment following code indentation
x = 10 # Inline comment with proper spacing
# UPPERCASE COMMENT
# Comment with special characters: @#$%^&*()
How Python Comments Work
The Python interpreter processes comments during the tokenization phase, completely removing them before code execution. This means Python comments have zero impact on program performance or functionality.
# The interpreter ignores this completely
def calculate_area(length, width):
# This comment explains the calculation
return length * width # Returns the area
When Python reads this code, it effectively sees:
def calculate_area(length, width):
return length * width
Python Comments vs Docstrings
While both Python comments and docstrings provide documentation, they serve different purposes:
Python Comments:
- Explain implementation details
- Provide context for complex logic
- Are ignored by documentation tools
- Use
#syntax
Docstrings:
- Document function, class, or module purpose
- Accessible at runtime via
__doc__attribute - Used by documentation generators
- Use triple quotes syntax
def greet_user(name):
"""
This is a docstring that documents the function's purpose.
It explains what the function does and its parameters.
"""
# This comment explains the implementation
formatted_name = name.capitalize() # Capitalize first letter
return f"Hello, {formatted_name}!"
Best Practices for Python Comments
Writing effective Python comments requires following established conventions:
Write clear, concise comments:
# Calculate compound interest
interest = principal * (1 + rate) ** time
Avoid obvious comments:
# Bad: increment x by 1
x += 1
# Good: Track the number of processed items
items_processed += 1
Update comments when code changes:
# Calculate monthly payment (updated for new interest formula)
monthly_payment = loan_amount * (rate / 12) * (1 + rate/12)**months
Python Comments for Code Organization
Python comments help organize code into logical sections:
# ==========================================
# DATA PROCESSING SECTION
# ==========================================
# Read input data
data = read_csv_file("sales_data.csv")
# Clean and validate data
cleaned_data = remove_invalid_entries(data)
# ==========================================
# ANALYSIS SECTION
# ==========================================
# Calculate monthly totals
monthly_totals = calculate_monthly_sales(cleaned_data)
Temporary Code Disabling with Python Comments
Python comments allow you to temporarily disable code without deleting it:
def process_data(data):
# Original implementation
# result = old_processing_method(data)
# New implementation
result = new_processing_method(data)
# Debug code (temporarily disabled)
# print(f"Processing result: {result}")
return result
Python Comments in Different Contexts
Comments in Functions
def calculate_discount(price, discount_percent):
# Validate input parameters
if price < 0 or discount_percent < 0:
return 0
# Apply discount calculation
discount_amount = price * (discount_percent / 100)
final_price = price - discount_amount
return final_price
Comments in Classes
class BankAccount:
def __init__(self, account_number, initial_balance):
# Initialize account properties
self.account_number = account_number
self.balance = initial_balance
# Track transaction history
self.transactions = []
Comments in Loops
# Process each item in the inventory
for item in inventory:
# Check if item needs restocking
if item.quantity < item.minimum_stock:
# Add to reorder list
reorder_list.append(item)
Complete Python Comments Example
Here’s a comprehensive example demonstrating various Python comment techniques:
#!/usr/bin/env python3
"""
Student Grade Management System
This module handles student grade calculations and reporting.
"""
# Import required modules
import json
from datetime import datetime
class GradeCalculator:
"""A class to calculate and manage student grades."""
def __init__(self):
# Initialize grade storage
self.grades = {}
# Set default grade weights
self.weights = {
'homework': 0.3, # 30% of final grade
'midterm': 0.3, # 30% of final grade
'final': 0.4 # 40% of final grade
}
def add_student_grade(self, student_id, assignment_type, score):
"""Add a grade for a specific student and assignment type."""
# Validate input parameters
if not isinstance(score, (int, float)) or score < 0 or score > 100:
raise ValueError("Score must be a number between 0 and 100")
# Initialize student record if doesn't exist
if student_id not in self.grades:
self.grades[student_id] = {
'homework': [],
'midterm': [],
'final': []
}
# Add grade to appropriate category
self.grades[student_id][assignment_type].append(score)
# Log the grade entry
print(f"Added {assignment_type} grade {score} for student {student_id}")
def calculate_final_grade(self, student_id):
"""Calculate the final weighted grade for a student."""
# Check if student exists
if student_id not in self.grades:
return None
student_grades = self.grades[student_id]
final_grade = 0
# Calculate weighted average for each category
for category, weight in self.weights.items():
category_grades = student_grades[category]
# Skip empty categories
if not category_grades:
continue
# Calculate average for this category
category_average = sum(category_grades) / len(category_grades)
# Apply weight to category average
final_grade += category_average * weight
return round(final_grade, 2)
def get_grade_report(self, student_id):
"""Generate a detailed grade report for a student."""
# Calculate final grade
final_grade = self.calculate_final_grade(student_id)
if final_grade is None:
return f"No grades found for student {student_id}"
# Determine letter grade
if final_grade >= 90:
letter_grade = 'A'
elif final_grade >= 80:
letter_grade = 'B'
elif final_grade >= 70:
letter_grade = 'C'
elif final_grade >= 60:
letter_grade = 'D'
else:
letter_grade = 'F'
# Format report
report = f"""
Student ID: {student_id}
Final Grade: {final_grade}%
Letter Grade: {letter_grade}
Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
"""
return report.strip()
# Main execution
if __name__ == "__main__":
# Create grade calculator instance
calculator = GradeCalculator()
# Add sample grades for demonstration
# Student 1001 grades
calculator.add_student_grade("1001", "homework", 85)
calculator.add_student_grade("1001", "homework", 92)
calculator.add_student_grade("1001", "midterm", 78)
calculator.add_student_grade("1001", "final", 88)
# Student 1002 grades
calculator.add_student_grade("1002", "homework", 90)
calculator.add_student_grade("1002", "homework", 87)
calculator.add_student_grade("1002", "midterm", 85)
calculator.add_student_grade("1002", "final", 91)
# Generate and display reports
print("\n" + "="*50)
print("GRADE REPORTS")
print("="*50)
# Display reports for both students
for student_id in ["1001", "1002"]:
print(calculator.get_grade_report(student_id))
print("-" * 30)
# Show final grades summary
print("\nFINAL GRADES SUMMARY:")
for student_id in ["1001", "1002"]:
final_grade = calculator.calculate_final_grade(student_id)
print(f"Student {student_id}: {final_grade}%")
Expected Output:
Added homework grade 85 for student 1001
Added homework grade 92 for student 1001
Added midterm grade 78 for student 1001
Added final grade 88 for student 1001
Added homework grade 90 for student 1002
Added homework grade 87 for student 1002
Added midterm grade 85 for student 1002
Added final grade 91 for student 1002
==================================================
GRADE REPORTS
==================================================
Student ID: 1001
Final Grade: 85.8%
Letter Grade: B
Generated: 2025-07-13 10:30:15
------------------------------
Student ID: 1002
Final Grade: 88.55%
Letter Grade: B
Generated: 2025-07-13 10:30:15
------------------------------
FINAL GRADES SUMMARY:
Student 1001: 85.8%
Student 1002: 88.55%
This comprehensive example demonstrates how Python comments enhance code readability, explain complex logic, and provide context for different code sections. The comments help other developers understand the purpose of each function, the logic behind calculations, and the overall structure of the program.