Comments

A comment starts at a # and runs to the end of the line, and the interpreter discards it before the line runs. A # inside a string literal is text rather than a comment, which is how print("order #8814") prints the hash. Comments exist for the next reader of the file, who is usually the author 6 months later, during an incident, with no memory of why a line is the way it is. The code already says what it does; a comment that earns its place says why, or records a fact about the data that the code cannot show.

What a comment is for

Comments that earn their place
  • A fact about the data the code cannot show: the vendor feed sends prices in cents
  • A reason for a surprising choice: half rounds to even to match the ledger
  • A reference: the spec, ticket or formula a line implements
  • A warning: this column has been nullable since the 2025 migration
Comments that cost the reader
  • quantity = 3 # set quantity to 3, which the code already says
  • A commented-out block kept in case it is needed again
  • A comment that was true 3 edits ago and nobody updated
  • A header with the author's name and date, which version control records
"""Compute the subtotal for one checkout line."""

# The vendor feed sends prices in cents, never dollars.
unit_price_cents = 4999  # 49.99 USD on the storefront
quantity = 3

# print(unit_price_cents)
subtotal_cents = unit_price_cents * quantity
print(subtotal_cents)
print("# not a comment inside a string")
print(__doc__)

Output:

14997
# not a comment inside a string
Compute the subtotal for one checkout line.

The first line of the file is a string literal on its own, and a string in that position at the top of a file, a function or a class is a docstring: Python keeps it, exposes it as __doc__, and tools such as help() and documentation generators read it. The commented-out print never ran, and the # inside the last string printed as a character. The comment on the price line records a unit, which is the single most useful fact a comment can carry in a data job, since a wrong unit produces a number that looks right.

Comments that lie

A comment is text the interpreter never checks, so nothing stops it from drifting out of date. discount = subtotal * 0.15 # 10% loyalty discount has one number in the code and a different one in the comment, and a reader has no way to know which was intended. The habit that prevents drift is moving the fact into code the interpreter will enforce: a name such as loyalty_rate = 0.15 states the rate once, and a comment beside it then explains where 0.15 came from rather than repeating it.

A few conventions mark comments that tooling reads. # TODO: and # FIXME: are collected by editors and linters so unfinished work can be listed. # noqa on a line tells the linter to skip that line. A first line beginning #!/usr/bin/env python3 tells the operating system which interpreter runs the file. Each of these is still a comment to Python itself, discarded before the line runs, which is why a typo in one never raises an error.

A loader computes subtotal_cents = unit_price_cents * quantity and stores the result. Which comment beside that line earns its place?

Do
  • Name values for what they hold, with the unit in the name: unit_price_cents
  • Convert text from files and APIs with int() or float() before arithmetic; flags go through int()
  • Keep money as integer cents and format to dollars only for display
  • Use parentheses wherever precedence is a question, and augmented assignment for counters
  • Write comments that record a unit, a reason or a reference
Avoid
  • Rebind a built-in name such as sum, max or list
  • Compare floats with == or use or for a default where 0.0 is a real reading
  • Trust print(x) to tell text from numbers; use the = specifier
  • Leave a comment that restates the code or a block of commented-out code
  • Let a constant live in a comment instead of in a named variable

About this lesson

This section is part of the Python Foundations: Beginner lesson on DataDriven, the home of data engineering. Lessons cover SQL, Python, Spark, data modeling and pipeline architecture, and each section pairs its explanation with worked examples and practice you run as you go.