Writing Clear Code

Code for Computers and People

When you write a program, the code tells the computer what to do. However, the code does not always show a human reader why you chose that approach or what a step is meant to accomplish. Comments bridge that gap. They are notes written inside your code for other programmers and for your future self, while the Python interpreter ignores them completely.

The Hash Marker

In Python, a comment begins with the hash symbol, #. Once the interpreter encounters # on a line, it ignores everything from that symbol through the end of the line. The line break marks the end of the comment. Therefore, text after # is not treated as executable Python code.

print("Ready")  # Tell the reader what this output represents

Ready

Two Comment Positions

A comment can occupy its own line above the code it describes. This placement is useful when explaining the purpose of a section or introducing what happens next. A comment can also appear after a statement on the same line. This inline style is best for a short clarification about a specific operation or value.

# Prepare the value used by the next part of the program
amount = 25

amount = amount + 5  # Add the adjustment to the amount

Execution Versus Documentation

print("Ready")  # Explain this message

Commenting with Purpose

The most useful comments explain why the code was written, not merely what the code visibly does. A meaningful comment can explain a chosen approach, the problem a line solves, or an assumption behind a calculation. If the code already uses clear names and plainly shows what it does, a comment that repeats the action adds little information.

# Keep the adjustment separate so the original amount remains visible
amount = 25
adjustment = 5
total = amount + adjustment  # Combine the original amount with the adjustment

The first comment explains a reason for the structure of the code. The inline comment briefly clarifies the operation on its line. Both comments add information beyond simply repeating a variable name or copying the visible operation into natural language.

Common Commenting Mistakes

• Writing explanatory text without the # marker

  Python recognizes a comment only after it encounters the # symbol. Without that marker, the text is not identified as a comment.

  Fix: # Prepare the value used by the next part of the program

• Placing a long explanation in an inline comment

  Inline comments work best when they are short and focused on one operation or value.

  Fix: amount = amount + 5 # Add the adjustment

• Restating what clear code already says

  The comment repeats the visible operation instead of explaining the reasoning, purpose, or assumption behind it.

  Fix: total = amount + adjustment # Combine the original amount with the adjustment

• Treating a comment as executable code

  Everything after # is ignored through the end of the line, so the print operation does not execute.

  Fix: print("Ready") # Describe the output for a reader

Practice the Distinction

Key Takeaways

1. Python comments begin with # and continue to the end of the line.
2. The interpreter ignores comment text, so comments do not perform program operations.
3. Use a comment on its own line to explain the purpose of a section or the code that follows.
4. Use a short inline comment after a statement to clarify one operation or value.
5. Effective comments explain why the code exists or what reasoning it depends on, rather than merely repeating what the code says.