Comments in Python - Deep Dive

Overview - Comments in Python

What is it?

Comments in Python are lines in the code that the computer ignores when running the program. They are used to explain what the code does, making it easier for people to understand. Comments start with a # symbol for single-line comments or are enclosed in triple quotes for multi-line comments. They help programmers remember their thoughts or share ideas with others.

Why it matters

Without comments, code can be confusing and hard to follow, especially when it gets long or complex. Comments make it easier to maintain and update code later, saving time and reducing mistakes. They also help teams work together by clearly explaining what each part of the code is supposed to do. Without comments, even the original coder might forget their own logic after some time.

Where it fits

Before learning comments, you should know basic Python syntax like writing statements and using variables. After understanding comments, you can learn about documentation strings (docstrings) and best practices for writing clean, readable code. Comments are a foundational skill that supports writing professional and maintainable programs.

Mental Model

Core Idea

Comments are notes in your code that explain what the code does but do not affect how the program runs.

Think of it like...

Comments are like sticky notes you put on a recipe to remind yourself or others why you added a certain ingredient or step.

Code Line 1: print('Hello')  # This prints a greeting
Code Line 2: # This line is ignored by Python
Code Line 3: '''
Multi-line comment
explaining code
'''
Code Line 4: x = 5  # Set x to five

Build-Up - 7 Steps

1

Foundation

Single-line comments with # symbol

Concept: Learn how to write single-line comments using the # symbol.

In Python, any text after a # on the same line is a comment. The computer skips it when running the program. Example: # This is a comment print('Hello') # This prints Hello The first line is a comment and does nothing. The second line prints text, and the comment explains it.

Result

The program prints: Hello The comments do not appear in the output.

Understanding that # starts a comment helps you add explanations without changing how your program works.

2

Foundation

Multi-line comments with triple quotes

Concept: Use triple quotes to write comments spanning multiple lines.

Python allows multi-line comments by enclosing text in triple single or double quotes (''' or """). Example: ''' This is a multi-line comment. It can span several lines. ''' print('Done') Though technically these are strings, if not assigned or used, they act as comments.

Result

The program prints: Done The multi-line comment is ignored by Python.

Knowing triple quotes can hold multi-line comments helps you write longer explanations or temporarily disable code blocks.

3

Intermediate

Comments for code clarity and maintenance

🤔Before reading on: Do you think comments affect program speed or output? Commit to your answer.

Concept: Comments improve code clarity and help maintain code without changing its behavior.

Comments explain why code exists or how it works, not what it does (which should be clear from the code itself). Example: # Calculate area of circle radius = 5 area = 3.14 * radius ** 2 # Area formula Comments help others (and future you) understand your logic quickly.

Result

The program runs normally, but the comments make it easier to understand and update.

Recognizing that comments are for humans, not computers, helps you write meaningful notes that aid collaboration and debugging.

4

Intermediate

Using comments to disable code temporarily

🤔Before reading on: Can comments be used to stop code from running without deleting it? Commit to your answer.

Concept: Comments can temporarily disable code lines without deleting them, useful for testing or debugging.

By adding # before a line, you prevent it from running. Example: print('Start') # print('This line is disabled') print('End') Only 'Start' and 'End' print, the middle line is ignored.

Result

Output: Start End The commented line does not run.

Knowing how to disable code with comments helps you test parts of your program safely without losing code.

5

Intermediate

Best practices for writing effective comments

🤔Before reading on: Should comments explain what the code does or why it does it? Commit to your answer.

Concept: Good comments explain why code exists or decisions made, not just what the code does.

Avoid obvious comments like: x = 10 # Set x to 10 Instead, explain intent: # Use 10 as default user limit to prevent overload x = 10 Keep comments clear, concise, and updated to avoid confusion.

Result

Comments become helpful guides rather than clutter or distractions.

Understanding the purpose of comments improves code readability and prevents misleading or outdated notes.

6

Advanced

Docstrings vs comments in Python

🤔Before reading on: Are docstrings and comments the same thing? Commit to your answer.

Concept: Docstrings are special multi-line strings used to document functions, classes, or modules, different from regular comments.

Docstrings use triple quotes right after a function or class definition. Example: def greet(): '''This function prints a greeting message.''' print('Hello') Docstrings can be accessed by tools and help generate documentation, unlike normal comments.

Result

Docstrings provide structured documentation accessible at runtime, while comments are ignored.

Knowing the difference helps you write professional code with built-in documentation for users and developers.

7

Expert

How comments affect Python bytecode and performance

🤔Before reading on: Do comments increase the size of the compiled Python bytecode? Commit to your answer.

Concept: Comments are removed during Python compilation and do not affect bytecode size or runtime performance.

When Python runs a script, it compiles it to bytecode, ignoring comments completely. This means comments have zero impact on speed or memory. Only docstrings remain in bytecode if not optimized away. Example: # This is a comment print('Hi') The comment is not in the compiled .pyc file.

Result

Comments do not slow down or increase the size of Python programs.

Understanding that comments vanish before execution reassures you that adding explanations won't harm performance.

Under the Hood

Python treats comments as non-executable text starting with # and ignores them during parsing. Multi-line comments using triple quotes are actually string literals not assigned to any variable, so Python discards them unless used as docstrings. During compilation, comments are stripped out, so they do not appear in the bytecode or affect runtime behavior.

Why designed this way?

The # symbol was chosen for simplicity and clarity to mark comments. Triple quotes were originally for multi-line strings but repurposed for multi-line comments due to Python's syntax simplicity. This design keeps code readable and clean without adding complex comment syntax, balancing human readability with interpreter efficiency.

Source Code
  │
  ├─ Lines starting with # ──> Ignored by parser
  │
  ├─ Triple-quoted strings not assigned ──> Treated as no-op strings
  │
  └─ Other code lines ──> Compiled to bytecode

Bytecode
  └─ Contains only executable instructions, no comments

Myth Busters - 4 Common Misconceptions

Quick: Do comments slow down your Python program when it runs? Commit to yes or no.

Common Belief: Comments make the program slower because they add extra text.

Reality: Comments are removed before the program runs and do not affect speed or memory.

Why it matters: Believing comments slow programs might discourage writing helpful explanations, making code harder to maintain.

Quick: Can triple-quoted strings always be used as comments? Commit to yes or no.

Common Belief: Triple quotes are official multi-line comments and behave exactly like # comments.

Reality: Triple quotes create string objects; if not assigned, they act like comments but can cause unexpected behavior if placed incorrectly.

Why it matters: Misusing triple quotes can lead to subtle bugs or memory use if strings are created unintentionally.

Quick: Should comments explain what the code does line-by-line? Commit to yes or no.

Common Belief: Comments must describe every line's action to be useful.

Reality: Good comments explain why or the intent, not obvious code actions, to avoid clutter and confusion.

Why it matters: Over-commenting wastes time and makes code harder to read, hiding important explanations.

Quick: Are docstrings and comments interchangeable? Commit to yes or no.

Common Belief: Docstrings are just fancy comments and serve the same purpose.

Reality: Docstrings are special strings used for documentation and can be accessed programmatically, unlike comments.

Why it matters: Confusing them leads to poor documentation practices and missed opportunities for automated help.

Expert Zone

1

Comments should be updated alongside code changes; outdated comments cause more harm than no comments.

2

Using comments to explain complex algorithms is better than trying to simplify code excessively, which can reduce performance or clarity.

3

Docstrings can be parsed by tools like Sphinx to generate professional documentation, bridging code and user manuals.

When NOT to use

Avoid using comments to explain poorly written code; instead, refactor the code for clarity. Also, do not use triple-quoted strings as comments inside functions where docstrings belong. For disabling large code blocks, consider version control or feature flags instead of long comment blocks.

Production Patterns

In professional codebases, comments are used sparingly to explain non-obvious logic, assumptions, or workarounds. Docstrings document APIs and modules. Comments often include TODOs or FIXMEs for future work. Code reviews check for meaningful comments and remove outdated ones to keep code clean.

Connections

Documentation Strings (Docstrings)

Builds-on

Understanding comments prepares you to use docstrings, which are structured comments that document code for users and tools.

Version Control Systems (e.g., Git)

Complementary

Comments help explain code changes, but version control tracks history and context, together improving code maintenance.

Human Communication

Analogous

Comments are a form of communication between programmers, similar to how people leave notes or instructions for each other in daily life.

Common Pitfalls

#1 Writing comments that just restate the code without adding meaning.

Wrong approach:

x = 10 # Set x to 10
print('Hello') # Print Hello

Correct approach:

# Use 10 as default user limit to prevent overload
x = 10

# Greet the user
print('Hello')

Root cause:

Misunderstanding that comments should explain intent or reasoning, not obvious actions.

#2 Using triple quotes for multi-line comments inside functions where docstrings belong.

Wrong approach:

def func():
'''This is a comment, not a docstring.'''
pass

Correct approach:

def func():
"""This is a proper docstring describing the function."""
pass

Root cause:

Confusing multi-line comments with docstrings and their roles in documentation.

#3 Leaving outdated comments that no longer match the code.

Wrong approach:

# Calculate area of square
area = length * width

Correct approach:

# Calculate area of rectangle
area = length * width

Root cause:

Failing to update comments when code changes, causing confusion.

Key Takeaways

Comments are ignored by Python and serve only to explain code to humans.

Use # for single-line comments and triple quotes for multi-line comments or docstrings.

Good comments explain why code exists or decisions made, not just what the code does.

Comments do not affect program speed or size because they are removed before execution.

Docstrings are special comments used for documentation and differ from regular comments.