iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Triple quotes do not make Python comments. They delimit a string literal; Python treats that string as a docstring only when it is the first statement in a module, class, function, or method body. For ordinary explanatory notes that Python should ignore, use #.
Why triple-quoted “comments” do not document your code
A block wrapped in ''' or """ may look like a comment, but Python parses it as a string literal. Triple quotes allow a string to span multiple lines, and those lines are part of the string’s content. The Python Language Reference defines comments separately: a comment starts with a hash character that is not inside a string literal and ends at the physical line’s end.
Placement determines whether a string literal serves as an object’s docstring. If it is the first statement in a module, class, function, or method, Python makes it available through that object’s __doc__ attribute. A triple-quoted string elsewhere is still a string, but it does not become that object’s runtime docstring.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchChoose a comment or docstring based on what you mean
| Construct | Purpose | Placement and behavior |
|---|---|---|
# explanation |
Commentary for people reading the code | Put it on an applicable code line; Python ignores it as syntax. |
"""multiline text""" in an arbitrary position |
A string literal | Can span lines, but does not automatically document an object. |
| First string-literal statement in a module, class, function, or method | Documentation attached to that object | Python exposes it as the object’s __doc__. |
Put a function docstring first
Place a function’s docstring immediately after its def line, before any other statement. Use hash-prefixed comments for notes that are not the function’s documentation.
#1 Best Overall
# This is a comment: Python ignores it as syntax.
def parse_record(text):
"""Parse one record and return its fields."""
# This comment is not part of the docstring.
return text.split(",")The docstring is available as parse_record.__doc__. By contrast, this misplaced string does not document the function:
def parse_record(text):
result = text.strip()
"""This is a string expression, not the function's docstring."""
return resultTo make that text the function’s docstring, move it directly under the def line. If it is only an explanatory note, change it to a # comment.
How to write useful comments and docstrings
Comments for code-level explanations
PEP 8’s block-comment convention is to start each line with # followed by a space. Keep comments clear and current; a stale comment can mislead readers about what the code does.
Recommended Free Tools
Docstrings for public interfaces
PEP 8 recommends docstrings for public modules, functions, classes, and methods. PEP 257 recommends triple double quotes, including for one-line docstrings. For a longer docstring, its convention is to begin with a summary line, add a blank line, then provide further detail.
When relevant, explain behavior, arguments, return values, side effects, exceptions, or restrictions on how the function may be called. Avoid a docstring that merely repeats what obvious code already says, and keep documentation accurate as the implementation changes.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Two special PEP 257 terms
PEP 257 describes “attribute docstrings” and “additional docstrings”: string literals that appear after certain assignments or after another docstring. Some documentation tools may extract these strings, but they are not assigned to an object’s runtime __doc__ attribute. For documentation directly available on a module, class, function, or method, the dependable rule is to put its docstring first.
Quick Recap
Official references
- Python 3.14.8 Language Reference: Lexical analysis explains comments and string literals.
- PEP 257 – Docstring Conventions covers docstring placement and conventions.
- PEP 8 – Style Guide for Python Code covers block comments and public docstrings.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →
