Clean Code and Useful Comments 🧹

Imagine a workbench after a large project: the tools are useful, but empty boxes and old drafts get in the way. Code works the same way. Once a program runs, remove experimental leftovers and make it understandable for the next reader — even if that reader is you tomorrow.

Clear Names Instead of Riddles

# Unclear
h = 20
d = 0.3

# Clear
flight_height = 20
frame_delay = 0.3

A good name explains what a variable stores. Python developers use snake_case for regular variables.

Settings that should not change while the program runs conventionally use UPPER_CASE:

FLIGHT_HEIGHT = 20
RESET_COLOR = '\033[0m'

Separate Meaningful Sections

A blank line makes the file structure visible:

import time

FLIGHT_HEIGHT = 20
FRAME_DELAY = 0.3

print('Preparing for launch')
time.sleep(FRAME_DELAY)

Imports usually come first, followed by settings and data, then the program commands.

Remove Experimental Leftovers

After testing, a file may contain old formulas, duplicate commands, and commented-out code versions:

# delay = 1
# delay = 0.5
delay = 0.3

Delete old versions when they are no longer needed. They distract readers and make them wonder which line is correct. An editor can undo a recent deletion, while Git preserves history in real projects.

Comments Should Explain a Reason

A comment that only repeats the code does not help:

# Wait for one second
time.sleep(1)

A useful comment explains a decision that the command alone cannot show:

# Give CodeHS enough time to render the new frame.
time.sleep(0.1)

Comments are helpful for environment limitations, unusual formulas, and reasons behind a non-obvious choice. Keep each comment updated when the code changes.

Do Not Break the Program While Cleaning

Change one small piece at a time:

1. Remove one unnecessary line.
2. Run the program.
3. Confirm that the result is unchanged.
4. Move to the next piece.

This makes it easy to identify which change caused an error.

Quick Check

• Names explain what variables are for.
• Settings are grouped and use UPPER_CASE.
• Working variables use snake_case.
• The file contains no old or duplicate code versions.
• Comments explain reasons instead of reading commands aloud.
• The program behaves the same after cleanup.

Clean code is not the shortest code or code with no comments at all. It is code where you can quickly find the right place and safely make the next change.