DoAssignment study guide
A4.2 · Use clear names, indentation, and comments
Learn to use clear names, indentation, and comments through clear examples and targeted practice.
Ontario Grade 11 Computer Science
Programming Concepts and Skills
Ontario Grade 11 Computer Science — A4.2: Use clear names, indentation, and comments
Readable code is code that another person can follow without having to guess what its names mean or which instructions belong together. In this lesson, you will practise three habits named in expectation A4.2: clear names, indentation, and comments. These habits do not change what a program is meant to do; they make its instructions easier to understand and maintain. The examples use Python 3. Other classrooms may use a different programming language, so their exact indentation rules or comment symbols may differ.
What you will learn
- Choose names that make a variable’s purpose clear.
- Use consistent indentation to show which instructions belong together.
- Write brief, useful comments that explain code when needed.
- Trace a short program to describe its expected output.
1. Choose names that explain purpose
A name is a label for information a program stores. A clear name gives a reader a useful clue about what that information represents. For example, a name such as minutes_read is more informative than x if the value represents reading time. Choose names that match the problem, and use the same name consistently.
In Python 3, variable names are case-sensitive: minutes_read and Minutes_Read are different names. A name cannot contain spaces, so an underscore can separate words. Avoid names that are so short or general that a reader must search elsewhere to guess their meaning. Also avoid changing a name halfway through a program unless you deliberately update every place that uses it.
Input, process, and output help organize a small example. The input is the information supplied to the program; the process uses that information; and the output is what the program displays. Clear names help a reader recognize each part.
- Name a value for its role in the problem.
- Use one spelling and capitalization consistently.
- Python 3 names do not contain spaces and are case-sensitive.
2. Indent instructions to show their grouping
Indentation means leaving spaces before an instruction. In Python 3, indentation shows which instructions belong inside a group, such as the instructions following an if statement. Use the same indentation pattern for instructions at the same level. A consistent pattern makes the program’s grouping visible and helps prevent mistakes.
Do not add or remove indentation at random. If two instructions belong to the same group, line them up. If an instruction belongs inside another instruction’s group, indent it farther. Python 3 commonly uses four spaces for each indentation level; a class using another language may use different conventions.
A comment is a note for a human reader. In Python 3, a comment begins with # and continues to the end of that line. A useful comment explains a reason, a choice, or a detail that may not be obvious from the code. Comments should agree with the instructions: a comment that describes an old version of the program can confuse readers.
- Line up instructions that belong to the same group.
- Indent instructions inside a group consistently.
- Use comments to clarify code, not to repeat every instruction.
3. Read, trace, and improve a small program
A simple way to check whether code is readable is to trace it: follow the instructions in order and note how named values change. A trace describes what the shown code is expected to do; it is not a claim that the code was run. For a short program, a table can record each important value before the final output.
When revising code, keep its intended task in view. Improve unclear names, make the grouping easy to see, and add a comment only where it helps explain a choice. Then trace the revised instructions again. This checks that the names and notes still match the values and output.
- Trace instructions in their written order.
- Record changes to values before deciding what output is expected.
- Check that comments remain accurate after changes.
4. A quick readability review
Before sharing a short program, ask: Can a reader tell what the important names represent? Are instructions at the same level lined up? Does each comment add useful information, and is it still true? These questions focus on the three practices in A4.2 without requiring advanced programming techniques.
For each example below, first identify its input, process, and output. Next, read the Python 3 source from top to bottom. Follow the named values and use the trace table to derive the expected display.
- A readable program makes its meaning easier to follow.
- Names, indentation, and comments each help in a different way.
- The examples are text to study; no code is executed here.
Trace for the reading-time example
| Instruction followed | minutes_monday | minutes_tuesday | total_minutes |
|---|---|---|---|
| After first assignment | 18 | — | — |
| After second assignment | 18 | 22 | — |
| After addition | 18 | 22 | 40 |
Trace for the activity-time example
| Instruction followed | reading_minutes | writing_minutes | activity_minutes |
|---|---|---|---|
| After first assignment | 12 | — | — |
| After second assignment | 12 | 5 | — |
| After addition | 12 | 5 | 17 |
Worked example
Name a value by what it represents
A student reads for 18 minutes on Monday and 22 minutes on Tuesday. Make a short program that adds the two amounts and displays the total. The inputs are the two reading times; the process is addition; the output is the total minutes.
Python 3
minutes_monday = 18
minutes_tuesday = 22
total_minutes = minutes_monday + minutes_tuesday
print("Total minutes:", total_minutes)- Choose namesThe names minutes_monday and minutes_tuesday tell the reader what each input represents. The name total_minutes describes the result of adding them.
- Trace the valuesThe first two assignments store the stated times. The addition gives 40, so the display instruction is expected to show the total with its label.
Answer: Expected output: Total minutes: 40
Check: The result is 18 + 22 = 40 minutes. The names distinguish the two inputs from the calculated total.
Worked example
Indent a group consistently
A learner has 3 completed practice questions. If the number is at least 3, display a message of encouragement. The input is the number completed; the process checks that number against the stated condition; the output is the message if the condition is met.
Python 3
completed_questions = 3
if completed_questions >= 3:
print("Practice goal reached!")- Read the groupingIn Python 3, the indented print instruction belongs to the if statement. The clear name completed_questions describes the value being checked.
- Trace the conditionThe stored value is 3. Since 3 is at least 3, the indented instruction is part of the path followed, so the message is expected to display.
Answer: Expected output: Practice goal reached!
Check: The condition is true for the stated input, and the print instruction is indented as part of the if group.
Worked example
Use a comment to explain a choice
A classroom activity gives 12 minutes for reading and 5 minutes for writing. Display the total activity time. The inputs are the two time amounts; the process adds them; the output is the total. A comment explains why the times are added.
Python 3
reading_minutes = 12
writing_minutes = 5
# Add both parts to get the full activity time.
activity_minutes = reading_minutes + writing_minutes
print("Activity time:", activity_minutes, "minutes")- Read the comment and namesThe comment gives the reason for combining the two time values. The names reading_minutes, writing_minutes, and activity_minutes identify the parts and the result.
- Trace to the outputThe values 12 and 5 are stored, then added to make 17. The final instruction is expected to display the activity time and its value.
Answer: Expected output: Activity time: 17 minutes
Check: The comment matches the addition in the code. It adds context rather than merely repeating the assignment.
Common mistakes and how to avoid them
Using a name such as x for an important value even when its meaning is not clear from the surrounding code.
Correction: Choose a name that describes the value’s role, such as completed_questions or total_minutes.
Indenting instructions in the same group by different amounts.
Correction: Line up instructions at the same level. In Python 3, indent an instruction that belongs inside a group, such as the body of an if statement.
Writing a comment that restates the code without adding useful information, or leaving a comment that no longer matches the code.
Correction: Use a brief comment to explain a reason or detail that is not obvious, and check that it stays accurate when the code changes.
Lesson summary
- Clear names help readers identify what stored values represent.
- Consistent indentation shows how instructions are grouped; in Python 3 it is part of the syntax.
- Comments are notes for readers and should clarify code without contradicting it.
- Tracing values from input through process to output helps verify what the shown instructions are expected to display.
Check your understanding
Question 1
Which name is clearest for a value that stores the number of pages read today?
- x
- pages_read_today
- thing
- correctIndex
Show answer and explanation
pages_read_today
pages_read_today tells the reader what the stored value represents.
Question 2
In the second worked example, why is the print instruction indented?
- It belongs to the if group and is displayed when the condition is true.
- Indentation changes the value of completed_questions.
- Every Python 3 instruction must be indented.
- correctIndex
Show answer and explanation
It belongs to the if group and is displayed when the condition is true.
The indentation shows that print belongs to the if statement’s group.
Question 3
Which comment is most useful above code that adds two parts of an activity?
- This is code.
- Add both parts to get the full activity time.
- The answer is always 17 minutes.
- correctIndex
Show answer and explanation
Add both parts to get the full activity time.
It explains the purpose of the addition without claiming that the total is always the same.
Key terms
- Variable
- A named place in a program where a value is stored.
- Indentation
- Spaces at the start of a line that show how an instruction is grouped.
- Comment
- A note in source code for human readers; Python 3 comments begin with #.
- Trace
- A step-by-step record of how instructions use or change values.
Continue through ICS3U
View the complete ICS3U Ontario Grade 11 Computer Science curriculum and lessons
- A4.1 · Find and correct syntax, logic, and run-time errors
- A4.3 · Interpret programming-tool error messages
- A1.1 · Use variables and constants with appropriate data types
- A1.2 · Explain binary, hexadecimal, and character encoding
- A1.3 · Use arithmetic and string assignment statements
- A1.4 · Use Boolean, comparison, and arithmetic operators correctly
About this lesson and its review
Published by DoAssignment. This reviewed lesson follows Ontario Grade 11 Computer Science (ICS3U), expectation A4.2. It is a study resource, not an official curriculum publication.
Before publication, content is checked for structure, mathematical or chemical notation, calculations, course boundaries, and readability. Errors can still occur, so corrections are welcomed.