I still see the same failure mode in code reviews year after year: a tricky block of Python lands in a repository with just enough context to work today, and just little enough context to confuse everyone six weeks later. The author “knows what it does,” the tests pass, and the PR gets merged—until someone needs to modify it, and now they’re reverse-engineering intent from raw syntax. That’s where multiline comments matter.

Python doesn’t ship a dedicated multiline-comment token like / ... /. Instead, you combine a few idioms—mostly repeated # lines, sometimes docstrings, and occasionally a triple-quoted string literal expression—to leave durable explanations, temporarily disable code, or attach tool directives.

What I like about Python’s approach is that it pushes you toward clarity: comments are explicit, line-based, and easy for tooling to reason about. What I dislike is how easy it is to misuse triple quotes and accidentally create “comments” that behave like runtime string objects.

You’ll leave with concrete patterns I rely on in production: when I repeat #, when I write docstrings, when I avoid triple quotes, and how modern linters and AI-assisted editors in 2026 change what “good commenting” looks like.

What Python Actually Treats as a Comment

At the language level, Python comments are simple: anything after # on a physical line is ignored by the parser (with a few special cases like encoding declarations). That simplicity has consequences you can count on:

• A # comment has zero runtime cost because it never becomes bytecode.
• A # comment can appear almost anywhere: top-level, inside blocks, at the end of a statement, or on its own line.
• A # comment can’t span multiple physical lines by itself—so “multiline comments” are really a convention, not a feature.

There are also “structured comments” that tools interpret even though Python itself ignores them. You’ve probably seen these:

• # noqa (various linters): suppress warnings for that line.
• # type: ignore (type checkers): ignore a type error on that line.
• # pylint: disable=... (pylint): toggle checks.
• Formatting toggles like # fmt: off / # fmt: on (for formatters that support it).

These aren’t multiline comments by default, but they shape how you should write your own multiline comment blocks. If your team relies on automated checks (most teams do), you want comments that are friendly to both humans and tools.

One subtle point: Python’s tokenizer, parser, and docstring rules make a strong distinction between:

• “real comments” (# ...) that disappear before execution, and
• “string literals” ("""...""") that may be kept as constants and sometimes become documentation metadata.

When you’re choosing an approach for multiline commentary, you’re really choosing between “purely ignored text” and “text that may live in the compiled artifact.”

The Default I Recommend: Repeating # (Yes, Even for Big Blocks)

If you want a multiline comment in Python, I recommend repeated # lines as your first choice. It’s the closest thing Python has to a native multiline comment, and it behaves exactly like you expect: it’s ignored completely.

Here’s a complete, runnable example that shows three common styles: a short block comment, an inline comment, and a “header” comment that frames a section.

def normalizecustomeremail(raw_email: str) -> str:
# We normalize emails to reduce duplicate accounts.
# - Trim whitespace
# - Lowercase
# - Keep domain intact (no provider-specific rewriting here)
cleaned = raw_email.strip().lower()
# Inline comments are great for “why,” not “what.”
return cleaned  # Avoids treating ‘[email protected]‘ and ‘[email protected]‘ as different
if name == ‘main‘:
print(normalizecustomeremail(‘  [email protected]  ‘))

When I’m writing repeated # comments well, I follow a few habits:

• I explain intent, not mechanics.

– Bad: # Lowercase the email (the code already says that).

– Good: # Lowercase so identity comparisons behave consistently across systems.

• I keep blocks shaped like prose, not like walls.

– If the comment is long, I add bullet points.

– I wrap at a reasonable line length so diffs stay readable.

• I keep the comment adjacent to what it explains.

– If the comment explains a function’s contract, I move it into a docstring.

– If it explains a single line’s oddness, I keep it inline.

In 2026 editors make this easier than it used to be. Most IDEs support toggling line comments for a selection (and respecting indentation), so “but it takes forever to add # on every line” just isn’t true anymore.

When repeated # beats every other approach

• You want a true comment, not a string literal.
• You’re temporarily disabling code and want the disabled block to be unmistakable.
• You’re writing guidance for future maintainers and you don’t want it to show up in help().
• You’re working in performance-sensitive or size-sensitive environments (CLI tools shipped as single binaries, serverless packaging constraints, etc.), and you’d rather not carry extra constants.

Triple-Quoted Strings: “Looks Like a Comment” Is Not the Same as “Is a Comment”

The most common “multiline comment” workaround is an unassigned triple-quoted string:

"""
I want to explain something in multiple lines.
This looks like a comment block.
"""

Here’s the crucial detail: that is not a comment. It’s a string literal expression.

Python may treat it as:

• a module docstring (if it’s the first statement in a module),
• a function/class docstring (if it’s the first statement in that scope), or
• a “do-nothing string expression” (if it appears elsewhere).

That last case is where teams get into trouble. The code “works,” so the pattern spreads, but it comes with drawbacks:

• Linters may flag it as a pointless statement (because it is).
• It can appear in the compiled constants, slightly increasing bytecode size.
• Readers may confuse it with a docstring and assume it has documentation semantics.

I’ll show all three behaviors in one runnable script:

"""Module docstring: shows up in help() and doc."""
def computetax(amountusd: float) -> float:
"""Return estimated tax for a purchase."""
rate = 0.0825
"""
This is NOT a docstring.
It‘s a string literal expression inside the function body.
Many linters will complain about it.
"""
return amount_usd * rate
if name == ‘main‘:
print(‘Module doc:‘)
print(doc)
print(‘\nFunction doc:‘)
print(compute_tax.doc)
print(‘\nTax:‘)
print(compute_tax(120.00))

My rule: I only use triple quotes for docstrings (real documentation), not as general multiline comments.

If you want a long explanation inside a function body, repeated # stays the cleanest, most tool-friendly choice.

Why “string literal comments” can surprise you

Even if the runtime overhead is usually negligible, the failure modes are annoying because they’re subtle:

• They can confuse coverage tools (a string expression can appear as a “statement” in some reporting).
• They can confuse auto-doc tools that scrape doc (people start hunting for documentation that isn’t real).
• They can create style drift: half the team uses #, half uses """, and now every file reads differently.

If you like the visual appearance of a big block, you can still get that with # by framing it cleanly:

# --- Pricing notes ----------------------------------------------------------
This function is intentionally conservative.
#
We only apply discounts that are (a) explicitly authorized and (b) stable
across all checkout surfaces.
---------------------------------------------------------------------------

Docstrings: Documentation That Ships With Your API

Docstrings are Python’s “official” multiline text feature for describing modules, functions, classes, and methods. Unlike # comments, docstrings are stored on the object and can be retrieved via doc or displayed by help().

That property makes docstrings ideal for:

• public library APIs,
• internal services with many callers,
• data pipelines where behavior must be stable across versions,
• teams that generate docs automatically (Sphinx, pydoc, MkDocs plugins, and similar tooling).

A docstring is simply a triple-quoted string that appears as the first statement in a module/function/class.

def formatreceiptline(itemname: str, quantity: int, unitprice_usd: float) -> str:
"""Format a receipt line for printing.
Args:
item_name: Human-readable name shown on the receipt.
quantity: Number of units purchased.
unitpriceusd: Price per unit in USD.
Returns:
A single line containing item name, quantity, and total.
Notes:
I keep this formatting logic here (instead of in the UI layer) so
receipts printed from batch jobs match receipts printed at checkout.
"""
total = quantity * unitpriceusd
return f‘{item_name} x{quantity} = ${total:.2f}‘
if name == ‘main‘:
print(formatreceiptline(‘USB-C Cable‘, 2, 9.99))
print(‘\nDocstring exposed via doc:\n‘)
print(formatreceiptline.doc)

A 2026 reality check: docstrings can be removed

If Python is run with optimization flags like -OO, docstrings can be stripped. That means:

• Docstrings are great for developer-facing documentation.
• Docstrings are not a reliable place to store runtime-critical strings.

If you need runtime-visible help text for a CLI, you should store it explicitly (for example, in a constant) rather than relying on doc.

Docstrings vs multiline comments (practical differences)

Feature

Multiline comment blocks (# on each line)

Docstrings ("""...""" as first statement) —

—

— Primary purpose

Explain implementation details, reasoning, gotchas

Document a public contract: module/class/function/method Runtime presence

Not present at runtime

Stored in doc (unless stripped) Best location

Anywhere (inside code blocks, near tricky logic)

Immediately after the definition line Tool integration

Linters/formatters generally ignore content

Doc generators and IDEs read and display them What I recommend

Default choice for multiline commentary

Use for APIs you expect others to call

Picking a docstring style (and keeping it consistent)

Most teams end up with one of these conventions:

• Google style: friendly, compact, common in application code.
• NumPy style: heavier, great for data/science libraries.
• reStructuredText (Sphinx): powerful, especially for published docs.

The specific style matters less than the consistency. I’d rather read 200 functions that all use the same docstring pattern than 20 functions that each invent their own. If your repo already uses a format, match it.

One practice I’ve adopted: if a function is internal and obvious, I skip docstrings and rely on names and small # comments. If it’s a boundary (API surface, integration point, or a function with non-obvious invariants), I add a docstring.

“Backslash Multiline Comments” and Other Myths

You’ll occasionally see people talk about a “backslash method” for multiline comments. In real Python, there are only a few relevant backslash facts:

• A backslash at the end of a line is a line continuation for Python code.
• A # comment ends the logical line as far as Python code is concerned.
• A backslash inside a # comment is just a character in text.

So this:

# This is a long comment \
that continues across lines \
because of the backslashes
print(‘Hello‘)

…does not “continue” anything. It’s simply three comment lines, each ignored by Python. The backslashes don’t change comment behavior.

The only time a backslash matters is when it’s part of actual Python syntax, like:

total = 10 + \
20 + \
30
print(total)

That is line continuation for code, not commenting.

My recommendation is blunt: don’t teach or adopt “backslash multiline comments” as a technique. If you want multiline comments, write multiline comments—repeat #.

Commenting Out Multiple Lines: How I Do It Without Regret

There are two reasons people reach for multiline comments:

• “I want to explain this block.”
• “I want to disable this block.”

Those are different needs, and I handle them differently.

Disabling code temporarily (short-lived)

If I’m experimenting locally, I’ll often comment out a block with repeated # lines because it’s explicit and reversible.

def loadcustomerprofile(customer_id: str) -> dict:
# Temporary: bypass external profile service while testing checkout UI.
# Remove this block before merging.
#
# profile = profileservice.fetch(customerid)
# return profile
return {‘customerid‘: customerid, ‘status‘: ‘stubbed‘}

If I see this in a long-lived branch, I treat it as a cleanup task. Dead code rots fast.

Disabling code in a shared branch (longer-lived)

When multiple people will pull the branch, I’d rather not leave commented-out chunks at all. Instead, I prefer one of these patterns:

1) Put the old path behind a feature flag.

def shouldusenew_pricing() -> bool:
return False  # Replace with real flag lookup
def computeprice(subtotalusd: float) -> float:
if shouldusenew_pricing():
return subtotal_usd * 0.97  # Promotional pricing path
return subtotal_usd

2) Use version control as the real “commenting system.”

• Commit the known-good version.
• Make the change.
• If you need the old version again, use git revert, git checkout, or git show.

I know that sounds obvious, but I’ve watched teams lose hours because they treated commented-out blocks as an archive.

A note about if False: blocks

You’ll see this trick:

if False:
print(‘Disabled code‘)

This prevents runtime execution, but it does not prevent parsing. Syntax errors inside the block still break your program. For quick local experiments it’s fine; for shared code it’s noisy.

If your goal is “temporarily disable these lines,” repeated # is clearer.

Tooling and Style in 2026: Comments That Work With Your Stack

Modern Python teams rarely read code in isolation. Your code is filtered through formatters, linters, type checkers, docs generators, and review tools. Multiline comments should cooperate with that ecosystem.

Formatters: keep intent readable

Formatters won’t reflow your comment text for you. That means you should write comments with diff-friendly wrapping.

If you need to preserve alignment in a block (for example, a hand-aligned table), some teams use formatter toggles:

# fmt: off
Country      Tax Rate
----------   --------
US           0.0825
CA           0.0750
fmt: on

Whether that’s worth it depends on your codebase. I only do this when alignment adds real readability.

Linters and type checkers: avoid “string-literal comments”

Tools generally agree on this:

• Repeated # is a comment.
• A random triple-quoted string in the middle of a function body is suspicious.

If your linter complains about a “pointless string statement,” it’s usually pointing at exactly that pattern. I treat the warning as a favor.

“Directive comments” should stay small and targeted

A directive comment is a comment you wrote for a tool, not for a human. Examples include:

• # noqa: E501
• # type: ignore[call-arg]

Keep these minimal, and add a human explanation when the reason isn’t obvious.

from typing import Any
def parse_event(payload: dict[str, Any]) -> str:
# The upstream system sometimes sends eventType as int; we normalize to str.
event_type = str(payload.get(‘eventType‘))
# type: ignore[return-value]  # Third-party stub is incorrect; upstream returns str here.
return event_type

Even if you don’t use that exact directive format, the habit is the same: the directive is the “what,” and your comment is the “why.”

Traditional vs Modern Commenting Habits (What I Changed in Recent Years)

A lot of Python commenting advice was written when teams were smaller and tooling was lighter. In 2026, you can be more consistent with less effort.

Area

Traditional habit

Modern habit I recommend —

—

— Multiline commentary

Triple-quoted blocks inside functions

Repeated # plus editor comment toggles API documentation

Sparse docstrings, details in wiki pages

Rich docstrings at boundaries; generate docs automatically “Why” explanations

Stored in tickets or chat logs

Co-locate the “why” as a short comment near the code Disabling code

Comment out large blocks and keep them

Prefer feature flags, deletes, and version control Tool directives

Sprinkle noqa / ignores without explanation

Keep directives narrow; add a one-line reason Code review

Assume reviewers infer intent

Write comments so reviewers can verify intent quickly

The biggest shift for me is that I assume future readers will be scanning. Comments now need to optimize for:

• searchability (someone will grep for a keyword),
• skimmability (diff views and mobile reviewers are real), and
• maintainability (if the code changes, the comment must still be true).

How I Write Multiline Comments That Age Well

If there’s one meta-skill here, it’s writing comments that don’t rot. A multiline comment is only valuable if it remains accurate after refactors.

1) Prefer invariants over step-by-step narration

Narration becomes outdated fast. Invariants age better.

• Narration: “We loop over rows, then compute totals, then subtract discounts.”
• Invariant: “Total must be monotonic with respect to quantity; discounts never increase total.”

Here’s an example where an invariant comment does real work:

def allocatebudget(totalcents: int, weights: list[int]) -> list[int]:
# Invariant: output sums exactly to total_cents.
# Invariant: allocations differ by at most 1 cent after rounding.
if total_cents < 0:
raise ValueError(‘total_cents must be non-negative‘)
if not weights or any(w < 0 for w in weights):
raise ValueError(‘weights must be a non-empty list of non-negative ints‘)
weight_sum = sum(weights)
if weight_sum == 0:
return [0 for _ in weights]
raw = [(totalcents * w) / weightsum for w in weights]
base = [int(x) for x in raw]
remainder = total_cents - sum(base)
# We distribute remainder by largest fractional parts to preserve fairness.
frac_order = sorted(
range(len(weights)),
key=lambda i: (raw[i] - base[i]),
reverse=True,
)
for i in frac_order[:remainder]:
base[i] += 1
return base

If someone later vectorizes this function, changes data structures, or swaps sorting logic, the invariants still apply and still guide the refactor.

2) Write the “because” sentence first

When I’m stuck, I force myself to start with “because.”

• “We do X because Y.”

That habit prevents comments that restate code. It also helps reviewers evaluate whether the reason is still valid.

# We cap retries because upstream rate-limits aggressively and excess retries
cause cascading latency under load.
MAX_RETRIES = 3

3) Separate explanation from instructions

A multiline comment sometimes mixes two types of information:

• Explanation: why this is the way it is.
• Instructions: what to do when it breaks.

I keep them separate so the “what to do” stays actionable.

# Explanation:
The payment provider can return duplicate webhook events.
We treat event_id as idempotency key to ensure exactly-once effects.
#
If this breaks:
- Check provider status page for webhook retries.
- Search logs for event_id collisions.
- Verify database unique constraint exists on (event_id).

4) Make the comment testable when possible

A comment is strongest when you can point at a test that enforces it. This is the best antidote to comment rot.

# This regex is intentionally strict; see testparseorderidrejects_lowercase.
ORDERIDRE = re.compile(r‘^ORD-[0-9]{10}$‘)

That line sends future maintainers to the test suite instead of a guessing game.

Multiline Comments Inside Complex Blocks: A Practical Pattern

Complexity tends to cluster around:

• error handling,
• data migration / backward compatibility,
• performance shortcuts,
• concurrency,
• boundary parsing.

In those places, I like a structured comment block with clear anchors. Here’s a pattern I use when a function has multiple “modes” or “phases.”

def ingest_record(record: dict) -> dict:
# Phase 1: normalize input
# - Accept legacy keys
# - Coerce types
# - Reject obviously invalid payloads early
normalized = {
‘id‘: str(record.get(‘id‘) or record.get(‘ID‘)),
‘timestamp‘: int(record.get(‘timestamp‘, 0)),
‘value‘: float(record.get(‘value‘, 0.0)),
}
# Phase 2: validation
# We validate after normalization so callers can be sloppy but we still
# enforce strong internal invariants.
if not normalized[‘id‘]:
raise ValueError(‘missing id‘)
if normalized[‘timestamp‘] <= 0:
raise ValueError(‘timestamp must be positive‘)
# Phase 3: enrichment
# This is deliberately pure (no network) so ingestion remains deterministic.
normalized[‘bucket‘] = normalized[‘timestamp‘] // 3600
return normalized

The comment headers double as a mini table-of-contents. Reviewers can quickly map a change to a “phase” and see whether invariants still hold.

When NOT to Write a Multiline Comment

Multiline comments have a cost: they ask future readers to trust your prose. I skip them when:

• The code can be made self-explanatory.

If the only reason for the comment is poor naming, rename instead.

• The comment would duplicate the test suite.

Tests should explain behavior; comments should explain intent and constraints.

• The comment is really a TODO.

If it’s an actionable work item, create a tracked task and keep the code clean.

• The comment would leak sensitive information.

Never put secrets, internal URLs, customer data, or incident details into code comments.

That last point deserves more emphasis than it usually gets. Comments are copied, grepped, indexed, and shipped. Treat them like code: they must be safe to share with anyone who has repo access.

Performance and Packaging: Do Comments Affect Runtime?

People sometimes ask whether comments affect runtime. The answer depends on which “comment” you mean.

• # comments are removed during tokenization and do not become bytecode.
• docstrings and standalone string literals can be present at runtime.

In most business applications, the difference is noise. Still, there are environments where bytecode size and import-time matter (serverless cold starts, CLI binaries, embedded Python, or big monorepos with many imports). In those environments I bias hard toward # blocks for internal notes and keep docstrings concise.

If you really need to verify whether a string literal is carried into constants, inspect the code object:

import dis
def f():
"""Docstring kept unless stripped."""
"""This is a pointless string statement."""
return 1
dis.dis(f)
print(f.code.co_consts)

I don’t recommend doing this frequently, but it’s useful once: it makes the distinction concrete.

Multiline Comments and Refactoring: Keeping Them in Sync

The hardest part isn’t writing comments; it’s keeping them true.

Here’s the workflow I follow during refactors:

• Scan for “because” comments first. Those encode constraints and can block a refactor.
• Treat comment changes as code changes. If a comment changes meaning, review it carefully.
• Delete stale comments aggressively. A wrong comment is worse than no comment.
• Prefer small comments near the code. Huge blocks are brittle unless they’re documenting invariants.

When a comment starts spanning more than a screen, I ask myself whether it belongs in:

• a docstring (if it’s part of the API contract),
• a design doc (if it’s architecture or business logic rationale), or
• a test (if it’s describing expected behavior).

Multiline comments are best when they’re tactical: attached to a specific block with a specific purpose.

AI-Assisted Workflows in 2026: Comments as Prompts (Without Being Weird)

AI tools changed how I think about comments in two ways.

1) Comments become retrieval anchors

When someone uses an AI assistant to navigate a codebase, the assistant often relies on embeddings and semantic search. A clear multiline comment can act like a high-signal anchor for:

• business terminology,
• tricky invariants,
• compatibility constraints,
• references to tests.

That doesn’t mean you should write comments “for the model,” but it does mean clarity pays dividends.

For example, a short block like this is searchable and useful:

# Compatibility:
We accept both snake_case and camelCase payload keys because mobile clients
shipped both formats across versions 4.1–4.3.

That kind of comment helps humans and helps tools.

2) Comments can prevent hallucinated refactors

When an assistant suggests a refactor, it can miss implicit constraints (like “we must not change rounding behavior”). A tight multiline comment stating the invariant reduces that risk, because the constraint is explicit.

The best practice I’ve found is to write constraints in a way that can be checked:

• “must not allocate more than N bytes”
• “must preserve stable sort order”
• “must keep output deterministic”

If it’s important, say it.

A Practical Checklist: My Default Multiline Comment Template

When I’m about to add a multiline comment block, I run this mental checklist. If I can’t answer at least one of these questions, I probably don’t need the comment.

• What is non-obvious here? (constraint, weird input, historical reason)
• What could go wrong? (edge cases, failure modes)
• How would someone debug it? (logs, metrics, tests)
• What must remain true after refactors? (invariants)
• Is there a better place? (docstring, test, design doc)

If I do write the block, I often use a consistent shape:

# Why:
...
#
Constraints:
- ...
- ...
#
Notes:
...

Even if I don’t include all sections, the headings keep the comment readable and stop me from rambling.

Common Pitfalls (and How I Avoid Them)

These are the mistakes I see most often with “multiline comments” in Python.

Pitfall 1: Using triple quotes as a general comment block

Fix: reserve triple quotes for docstrings.

Pitfall 2: Writing comments that restate code

Fix: start with “because” and focus on intent.

Pitfall 3: Keeping commented-out code for months

Fix: delete it, or use feature flags and version control.

Pitfall 4: Comment drift after changes

Fix: treat comment updates as part of the refactor; delete stale prose.

Pitfall 5: Using comments to hide complexity

Fix: refactor instead. If a function needs a page-long explanation, it probably needs to be decomposed.

Summary: My Recommendation in One Paragraph

If you want multiline comments in Python, use repeated # lines as your default because they’re real comments with zero runtime presence and the best tooling support. Use docstrings when you’re documenting a module, class, or function contract that callers rely on. Avoid unassigned triple-quoted strings inside code blocks because they’re not comments and they can confuse both humans and tools. And finally: write comments that explain “why,” encode invariants, and point to tests—those are the comments that still make sense six months later.