Python Comments — Why Deleting One Cost 4% Revenue

Every line of code you write today is a mystery you'll need to solve tomorrow. That sounds dramatic, but ask any developer who's opened a file they wrote six months ago — without comments, even your own code can look like a foreign language. Comments are the single cheapest investment you can make to keep your code readable, maintainable, and friendly to every person who touches it after you.

Python runs fast. It processes your instructions line by line, but it skips comments entirely — they exist purely for people, not machines. This solves a real problem: code tells the computer WHAT to do, but it rarely explains WHY a decision was made, what a tricky block is trying to achieve, or what a number like 0.0875 actually represents (is that a tax rate? a discount? who knows). Comments fill that gap.

By the end of this article you'll know exactly how to write single-line comments, how to fake multi-line comments the Pythonic way, how to use docstrings to document functions properly, and — most importantly — when to write a comment versus when to just write cleaner code. You'll also see the mistakes that trip up beginners and the answers that impress interviewers.

Single-Line Comments — The Workhorse You'll Use Every Day

A single-line comment in Python starts with the hash symbol #. Everything after that # on the same line is ignored by Python. That's the whole rule. There's nothing to install, no special mode to activate — just type # and write your note.

You can put a comment on its own line above the code it describes, which is called a 'block comment'. Or you can put it at the end of a line of code, which is called an 'inline comment'. Both are valid, but block comments are usually easier to read because they don't crowd the code.

Here's the key habit to build early: comment the WHY, not the WHAT. If you write total_price = price + tax and then comment # adds price and tax, that comment adds zero value — anyone can see that. But if you comment # tax is added here because EU law requires it to appear in the final total, now you've explained something the code can't explain itself. That's what comments are for.

Multi-Line Comments — What Python Actually Does (and Doesn't Have)

Here's something that surprises beginners: Python has no official multi-line comment syntax. Languages like Java and JavaScript have / ... / block comments, but Python never added an equivalent. So how do Python developers write longer notes that span multiple lines?

The answer is simple — you just start each line with its own #. Stack as many lines as you need, each prefixed with a #. Python treats each one as a separate single-line comment, but visually they read as a block. This is the officially recommended approach in Python's own style guide (PEP 8).

You'll also see beginners use triple-quoted strings (''' or """) as a workaround for multi-line comments. A string that isn't assigned to a variable and isn't attached to a function is technically just a value Python evaluates and immediately throws away — so it behaves like a comment in practice. However, this is not a true comment, and there's one important exception: when a triple-quoted string appears as the very first statement inside a function, class, or module, it becomes a docstring — a documented description that tools and IDEs can actually read. More on that in the next section.

Docstrings — Comments That Your Code Can Actually Read

A docstring is a special triple-quoted string placed as the very first statement in a function, class, or module. It's Python's official way of documenting what a piece of code does — and unlike a regular comment, Python stores the docstring and makes it accessible at runtime via the __doc__ attribute and the built-in help() function.

Think of a regular comment as a sticky note on your desk — helpful to you, invisible to everyone else. A docstring is like a label on a product — it's built into the thing itself and anyone can read it just by inspecting the object.

Docstrings follow a convention: the first line is a short, one-sentence summary of what the function does. If you need more detail, add a blank line, then a longer description, then document the parameters and return value. You don't have to memorise a rigid format right now — just know that the first line matters most and should be a clear, complete sentence.

For beginners, the most important takeaway is this: every function you write should have a docstring. It takes ten seconds, and it pays back tenfold.

Best Practices — When to Comment and When to Clean Code

Great developers don't write more comments — they write code that needs fewer comments. The best comment is a well-named variable, a clear function, or a small, focused method. But even the cleanest code can't express business context, historical decisions, or reasoning behind a non-obvious fix.

Here's the practical rule I use on every team: write a comment when the answer to 'Why is this here?' isn't obvious from reading the code alone. If you're explaining a workaround for a third-party bug, add a comment. If you're applying a formula that looks wrong but is correct for the business, add a comment. If you're adding a sleep() to avoid a race condition, for heaven's sake comment that — or it'll be removed in the next 'cleanup' PR.

Also: treat comments like code. They rot. A stale comment is worse than no comment because it actively misleads. During code review, ask the author if each comment is still accurate. Delete comments that describe what the code already says. Update comments when the logic changes.

Style and Conventions — PEP 8 and Team Standards

PEP 8, Python's official style guide, has clear rules for comments. Follow them and your team will read each other's code faster:

• Comments should be complete sentences. Start with a capital letter, end with a period.
• Use a space after #. It's # comment not #comment.
• Block comments apply to the following code. Indent them to the same level.
• Inline comments use at least two spaces between the code and the #.
• Docstrings use triple double quotes """ — triple single quotes ''' are acceptable but less common.

Most importantly: keep comments relevant. A comment that describes how code works is noise when the code is clear. A comment that describes why the code exists is gold.

Teams that enforce these standards through linters (flake8, pylint) catch comment style violations automatically. It's a small win, but it keeps the codebase consistent.

Frequently Asked Questions