Writing Clear Code

When you write a program, the code tells the computer what to do.

Programming

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.

Key point

A comment documents intent for people; it does not perform an operation for Python.

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.

python

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

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

Output

Ready

What part of a Python line does the interpreter process, and what part does it ignore after encountering #?

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.

python

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

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

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

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

What is the difference between a comment that introduces a code block and a comment that clarifies one operation?

Execution Versus Documentation

What do you think happens?

What output should this code produce?

Ready
Ready and Explain this message
No output

Reveal answer

Answer:

Ready

Python executes print("Ready"). After the # symbol, it ignores the remaining text on that line, so the comment cannot produce additional output.

python

print("Ready")  # Explain this message

print("Ready")  # Explain this message

Part of the line	Interpreter treatment	Human purpose
print("Ready")	Processed as code	Performs the operation
# Explain this message	Ignored through the end of the line	Documents intent

A line may contain executable code followed by a comment, but Python treats the two parts differently.

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.

python

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

# 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

Common mistake
Writing explanatory text without the # marker
What it looks like
Prepare the value used by the next part of the program
Why it fails
Python recognizes a comment only after it encounters the # symbol. Without that marker, the text is not identified as a comment.
Do this instead
```
# Prepare the value used by the next part of the program
```
Common mistake
Placing a long explanation in an inline comment
What it looks like
```
amount = amount + 5  # This line takes the amount that was previously stored and adds the adjustment so the resulting value can be used later
```
Why it fails
Inline comments work best when they are short and focused on one operation or value.
Do this instead
```
amount = amount + 5  # Add the adjustment
```
Common mistake
Restating what clear code already says
What it looks like
```
total = amount + adjustment  # Add amount and adjustment
```
Why it fails
The comment repeats the visible operation instead of explaining the reasoning, purpose, or assumption behind it.
Do this instead
```
total = amount + adjustment  # Combine the original amount with the adjustment
```
Common mistake
Treating a comment as executable code
What it looks like
```
# print("Ready")
```
Why it fails
Everything after # is ignored through the end of the line, so the print operation does not execute.
Do this instead
```
print("Ready")  # Describe the output for a reader
```

Practice the Distinction

EASY

Rewrite the following code so that it includes one full-line comment explaining the purpose of the calculation and one short inline comment clarifying the final operation:

value = 20
extra = 3
result = value + extra

Hints

Put the full-line comment above the related code.
Put the inline comment after the final statement.
Explain purpose or intent rather than repeating every visible operation.

Your attempt (not saved)

Worked example

One Possible Revision

Add a block comment and an inline comment to the calculation.

1
Explain the block's purpose
Place a comment on its own line above the statements to introduce what the calculation is for.
2
Clarify the final operation
Place a short comment after the final statement to clarify what the operation accomplishes.

Result

# Combine a base value with an additional amount
value = 20
extra = 3
result = value + extra  # Store the combined result

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.

At a glance

The # symbol starts a Python comment, and everything after it on that line is ignored.
Executable code tells Python what to do; comments document intent for human readers.
Full-line comments introduce or explain a block, while inline comments clarify a specific operation.
The strongest comments explain why a choice was made instead of restating visible code.

More concepts starting with W