Python Comments: Single-Line, Multi-Line, and Docstrings

Comments Are for Humans

Python ignores comments. That's the whole trick. Anything you mark as a comment is invisible to the interpreter — it's there purely for the person reading your code, which is usually future you, six months from now, wondering what past you was thinking.

That said, a comment that just echoes what the code obviously does isn't worth writing. The best comments explain why — a constraint, a workaround, a decision that isn't obvious from the code itself. The code already tells you what is happening.

Single-Line Comments With #

The basic form is a # followed by your note:

You can also tack a short comment onto the end of a line. By convention, leave at least two spaces before the #:

Python reads a # anywhere outside a string and treats the rest of the line as a comment. That "outside a string" part matters: # inside quotes is just a character.

The #section-2 inside the string is part of the URL. Python only flips into "comment" mode for the # after the string closes.

Commenting Out Multiple Lines

Python has no /* */ block comment. To skip several lines, put # at the start of each:

You almost never type those #s by hand. Every decent editor has a "toggle line comment" shortcut that adds or removes # on every selected line:

• VS Code: Cmd + / (macOS) or Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / or Ctrl + /
• Vim: depends on your plugins; vim-commentary binds gcc for a single line and gc for a selection.

Learn the shortcut in your editor once, and "commenting out this block to try something" becomes a one-keypress operation.

The Triple-Quoted String Trick (and Why It's Not a Real Comment)

You'll sometimes see code like this:

Technically that's a string expression that gets discarded. Python parses it, evaluates it, and throws the result away. It behaves like a comment, but it isn't one. Stylistically, this is only a good idea in one specific place: as a docstring.

Docstrings: The One Place Triple Quotes Belong

A docstring is a triple-quoted string placed as the very first statement in a function, class, or module. Python recognizes it as documentation and makes it available at runtime via the help() function and the __doc__ attribute:

Two things make docstrings nice:

1. Tools like IDEs, help(), and documentation generators read them automatically. A comment above the function gets nothing of the sort.
2. They describe the function at the call site — when someone hovers over discount(...) in their editor, the docstring pops up as a tooltip.

There's a convention (PEP 257) for what goes in a docstring: a one-line summary on the first line, a blank line, then a longer description if needed. Don't stress about the exact format on day one — a plain one-liner is still much better than no docstring at all.

What Good Comments Actually Say

A few guidelines that save a lot of heartache down the line:

• Prefer describing why over what. # Loop over the users is noise; # Retry on 503 — Redis sometimes dies mid-deploy is gold.
• Update comments when you change the code. A wrong comment is worse than no comment. Stale comments actively mislead future readers.
• Don't comment out code and leave it there. If you don't need it, delete it. Version control remembers. A file sprinkled with commented-out blocks becomes untrustworthy fast.
• Skip the obvious. x = x + 1 # increment x adds nothing.

Bottom Line

Comments are free to write and cheap to skip. Reach for them when you're leaving a note a reader will thank you for — a subtle reason something works, a link to an issue, a warning about an edge case. Use docstrings when you're defining a function or class. Otherwise, let clear names and small functions do the talking.

You now have everything you need to read and write a Python file. The next chapter is where the language actually starts doing things: variables, data types, and the values Python can hold.