HumachLearnLearn · explore · apply
Start learning
Getting Started with Python · Lesson 5

Comments and Readable Code

Comments explain intent that is not obvious from the code itself.

ConceptWorked examplePracticeKnowledge check
Textbook walkthrough

Comments and Readable Code

Comments explain intent that is not obvious from the code itself. In Python, a line comment begins with # and is ignored by the interpreter. Readability also comes from meaningful names, small functions, consistent layout and code that expresses one idea at a time; comments should clarify why a choice exists rather than narrate every obvious operation.

Learning goal: explain why Comments and Readable Code behaves this way, apply it to a small example, and verify the result independently. Begin by being able to justify this first step: Use # for concise notes about intent, assumptions or non-obvious constraints.

Deeper walkthrough

Read Comments and Readable Code as a mechanism, not a recipe

Treat this as a sequence of observable decisions rather than one opaque command. Stage 1: Use # for concise notes about intent, assumptions or non-obvious constraints. Stage 2: Prefer descriptive names so the code explains what a value represents. Stage 3: Keep comments synchronised with the code when behaviour changes. Final checkpoint: Remove commented-out obsolete code from finished work; version control is a better archive.

Mechanism

Follow the transformation

Use # for concise notes about intent, assumptions or non-obvious constraints.

Prefer descriptive names so the code explains what a value represents.

Keep comments synchronised with the code when behaviour changes.

Evidence

Know what would convince you

  • Trace a tiny input by hand and compare the runtime result.
  • Inspect type, value/shape and any mutation/side effect explicitly.
Useful distinctionInput: Objects/values supplied to the operation.
How it works

Trace the mechanism step by step

  1. Use # for concise notes about intent, assumptions or non-obvious constraints.
  2. Prefer descriptive names so the code explains what a value represents.
  3. Keep comments synchronised with the code when behaviour changes.
  4. Use docstrings for public module/function/class documentation rather than long comment blocks.
  5. Remove commented-out obsolete code from finished work; version control is a better archive.
Worked demonstration

Readable calculation

# Revenue excludes refunded orders.
# Step 1 — Compute the right-hand expression and store its result in `net_revenue` for the next step.
net_revenue = gross_revenue - refunds
# Step 2 — Display the current value explicitly so the result/state can be inspected during execution.
print(net_revenue)
Expected / illustrative result
The comment records a business rule; the variable name records what the computed value represents.
Interpret the result.

For Comments and Readable Code, trace the specific input through the mechanism above and independently verify one returned value, state change or side effect.

Distinctions & related ideas

Place the concept correctly

InputObjects/values supplied to the operation.
StateNames or mutable objects that may change during execution.
OutputReturned value, side effect, file, plot or exception to inspect.
Use deliberately

When it is appropriate

Use Comments and Readable Code when it answers a defined question in Getting Started with Python and its inputs/assumptions match the current data or program state.

Boundary conditions

When to stop or reconsider

Reconsider Comments and Readable Code when the required information is unavailable, the operation would violate a validation/data boundary, or a simpler operation answers the question more transparently.

Common mistakes

Failure modes to recognise

  • Running the operation on the wrong object/type or in the wrong environment.
  • Inferring correctness from “no exception” without checking the produced value/state.
  • Hiding a boundary case instead of making its behaviour explicit.
Verification

How to check the result

  • Trace a tiny input by hand and compare the runtime result.
  • Inspect type, value/shape and any mutation/side effect explicitly.
  • Run an edge or invalid case and confirm the exception/behaviour is deliberate.
Hands-on practice

Demonstrate understanding

Try this:

Construct a tiny example of Comments and Readable Code. First use # for concise notes about intent, assumptions or non-obvious constraints. Then prefer descriptive names so the code explains what a value represents. Predict the result before execution and explain one boundary or failure case.

Use the smallest values that expose the language rule. Write the expected value and type first, then compare the actual state/output with that prediction.
Knowledge check

Check reasoning, not memorisation

Which approach best demonstrates understanding of Comments and Readable Code?

Quick reference

Remember the logic

Step 1Use # for concise notes about intent, assumptions or non-obvious constraints.
Step 2Prefer descriptive names so the code explains what a value represents.
Step 3Keep comments synchronised with the code when behaviour changes.
Step 4Use docstrings for public module/function/class documentation rather than long comment blocks.
Lesson summary

What to remember

  • Comments explain intent that is not obvious from the code itself. In Python, a line comment begins with # and is ignored by the interpreter. Readability also comes from meaningful names, small functions, consistent layout and code that expresses one idea at a time; comments should clarify why a choice exists rather than narrate every obvious operation.
  • Use # for concise notes about intent, assumptions or non-obvious constraints.
  • Running the operation on the wrong object/type or in the wrong environment.
  • Trace a tiny input by hand and compare the runtime result.