Comments, Names, and Clear Output

Unit ID: M01-U05 Estimated active time: 20-25 minutes

Code is read more often than it is written

Python must be able to execute your program. A person must also be able to understand it. Clear names, useful comments, and readable output help both the original author and the next reader.

Compare these programs.

x = 480
y = 3
z = x / y
print(z)

total_cost = 480
number_of_people = 3
cost_per_person = total_cost / number_of_people
print(cost_per_person)

Both produce 160.0. The second program makes the meaning visible.

Choose names that explain the role

A Python name should describe the information it holds.

Good beginner names:

• travel_cost
• number_of_days
• average_score
• course_name

Weak names:

• x
• thing
• data1
• final_final

Python names cannot contain spaces. A common style uses lowercase words joined with underscores. This is called snake_case.

Names may contain letters, numbers, and underscores, but they cannot begin with a number. They are case-sensitive: total and Total are different names.

Use comments to explain purpose

A comment begins with #. Python ignores the rest of that line.

# All amounts are fictional and use Indian rupees.
breakfast_cost = 120
travel_cost = 250

The comment adds information the code cannot show by itself.

Avoid comments that merely repeat the instruction:

travel_cost = 250  # Set travel_cost to 250

Prefer a reason, assumption, unit, or limitation:

travel_cost = 250  # Return journey for one day

Make output meaningful

This output is technically correct but unclear:

370

Add a label:

print("Total cost:", breakfast_cost + travel_cost)

Output:

Total cost: 370

The comma allows print() to display text and a number together. Module 2 will teach more precise string formatting.

Build a first readable program

Read this program before running it:

# Fictional one-day workshop expenses in Indian rupees
travel_cost = 250
lunch_cost = 180
materials_cost = 320

total_cost = travel_cost + lunch_cost + materials_cost
average_cost = total_cost / 3

print("Total cost:", total_cost)
print("Average cost:", average_cost)

Predicted output:

Total cost: 750
Average cost: 250.0

Blank lines do not change the calculation. They separate the inputs, calculations, and output so the program is easier to scan.

Guided change

Add a fictional printing_cost of 90.

You must change more than one line:

1. Create the new value.
2. Include it in total_cost.
3. Change the divisor for average_cost from 3 to 4.

Then run the program. The new total should be 840, and the average should be 210.0.

This is an important lesson: when an input changes, dependent calculations may also need to change.

Check your work

Ask:

• Can a new reader tell what each value means?
• Are units or assumptions stated where needed?
• Does each comment add useful information?
• Does the output explain itself?
• Did every dependent calculation change with the new input?

Takeaway

Readable code is part of correctness. Use names that show meaning, comments that explain purpose or assumptions, and output labels that help a person interpret the result. Next, we will learn how to ask Python for help and how to read the first useful part of an error.