DoAssignment.ca

DoAssignment study guide

B3.2 · Document a program for later readers

Learn to document a program for later readers through clear examples and targeted practice.

Ontario Grade 10 Computer Science

Introduction to Programming

ICS2O study topic B3.2: make a program understandable to someone who reads it later

A program may work today, but another person might need to read or change it later. That person could be you after a few weeks. Documentation is information written with or alongside a program to help readers understand its purpose and how its parts work. In this lesson, you will practise using clear names and useful comments. These practices do not change the program's instructions; they make those instructions easier to understand.

What you will learn

  • Explain why a program should include documentation for later readers.
  • Use clear names and brief comments to explain a program's purpose and less-obvious steps.
  • Check that documentation matches what the code actually does.

1. What documentation is for

Imagine a student writes a small program to calculate the total cost of items for a school event. The program takes a number of items and a cost per item as input, processes them by multiplying the two values, and displays the total as output. A later reader needs to know what the program is for and what its values mean.
Documentation is not a second program and does not replace the instructions the computer follows. It is reader-focused information. In Python, a comment begins with the # character. Python ignores the comment when following the program, but a person can read it. A helpful comment gives context that may not be obvious from the code.
Clear names are another way to document a program. For example, item_count tells a reader more than x, and cost_per_item tells more than y. A name should describe the value it represents. Keep names connected to the program's actual purpose.
  • Input is information the program receives.
  • Process is the work the program does with its input.
  • Output is information the program presents.
  • Documentation helps a person understand the program; it does not make the program correct by itself.

2. Write documentation that helps

Start by making the program's purpose clear. A short opening comment can say what task the program performs. Then use descriptive names for values, so readers do not have to guess what they represent.
Add a comment when a reader might wonder why a step is there or what an important value means. A comment should add useful information rather than repeat a line in different words. For example, a comment saying “multiply the item count by the cost” above a line that visibly multiplies those values may add little. A comment explaining that the entered cost is for one item can clarify the meaning of the calculation.
Documentation must stay accurate as code changes. If a program is revised, read its comments again. A misleading comment can confuse a later reader more than no comment at all. A useful check is to compare each comment with the code directly below or near it.
  • Use a brief purpose comment when it helps explain the program's overall task.
  • Choose names that communicate what a value means.
  • Write comments for the reader, not to narrate every obvious instruction.
  • Update documentation when the program changes.

3. Read and review documented code

Consider a program that asks for the number of notebooks and the price of one notebook, then calculates the total. A reader can follow it by identifying the input lines, the calculation, and the displayed result. Names such as notebook_count and price_per_notebook make the process easier to follow.
A comment should describe the code that is actually present. If the code calculates a total before tax, a comment should not claim that it includes tax. If a program's input is a price for one item, documentation should not describe it as the price for all items.
When reviewing someone else's program, ask: What is its purpose? What do its important names mean? Do the comments explain something useful? Do they agree with the instructions? These questions focus on documentation rather than adding new programming features.
  • Follow the program from input, through process, to output.
  • Compare comments with the code instead of assuming comments are correct.
  • Prefer a small number of useful details over many repeated comments.

4. Practise documenting a small program

To practise, take a short program you already understand. Write one brief sentence describing its purpose. Rename unclear values so their meaning is easier to see. Add a comment only where it would help a later reader understand context or an important choice.
Then read the program as if you had never seen it before. Can you identify its input, process, and output? Does each comment match the code? Remove or correct any comment that repeats the code without helping, or that describes an earlier version.
The examples below use Python 3. They are shown as text and are not claimed to have been run. A classroom may use a different programming language; the exact comment mark and naming style can differ, while the goal remains to help later readers.
  • Document the program that exists, not the program you intended to write.
  • Clear names and accurate, purposeful comments work together.
  • Before sharing a program, read its documentation for clarity and accuracy.

Worked example

Example 1: Make a program's purpose clear

A program asks how many reusable cups are needed for an event and displays that number back to the user. Improve the documentation so a later reader can quickly understand the task and the input value.

Python 3

# Ask for the number of reusable cups needed at an event.
cup_count = input("How many cups are needed? ")
print("Cups needed:", cup_count)
  1. Describe the task
    A short purpose comment tells the reader what the program is for. The name cup_count then makes the input's meaning visible in the code.
  2. Trace the example input
    For the example input 24, the program stores 24 as the cup count and displays a sentence containing 24. The input is the count typed by the user; displaying the sentence is the output.
Answer: The purpose comment and the descriptive variable name make the program's task and input easier to recognize.
Check: The comment describes the program's purpose, and cup_count matches the value entered and displayed.

Worked example

Example 2: Explain an important value

A school club records how many tickets were sold and the price of one ticket. Document the calculation so a later reader understands what the price represents.

Python 3

# Find the ticket revenue before any other costs.
ticket_count = int(input("Tickets sold: "))
# This is the price for one ticket.
price_per_ticket = float(input("Price per ticket: "))
total = ticket_count * price_per_ticket
print("Total ticket revenue:", total)
  1. Name the values
    ticket_count and price_per_ticket tell the reader what each value represents. The comment clarifies that the price is for one ticket, which helps explain why it is multiplied by the number sold.
  2. Follow input, process, and output
    For a hypothetical input of 8 tickets and a price of 3.5 per ticket, the process multiplies 8 by 3.5. The expected displayed total is 28. This example describes a trace; the code has not been run.
Answer: The variable names and comment explain the calculation's meaning without commenting on every instruction.
Check: The comment accurately describes price_per_ticket, and the displayed total corresponds to the multiplication in the code.

Worked example

Example 3: Check that a comment is still accurate

A program calculates the number of pages a student plans to read over several days. Review the documentation and make sure it matches the code.

Python 3

# Estimate planned reading pages across several days.
pages_per_day = int(input("Pages planned each day: "))
number_of_days = int(input("Number of days: "))
planned_pages = pages_per_day * number_of_days
print("Planned pages:", planned_pages)
  1. Compare comment and calculation
    The comment says the program finds the planned total pages. The code multiplies pages_per_day by number_of_days, so the comment agrees with the process.
  2. Trace a sample
    For the hypothetical inputs 12 pages per day and 5 days, the calculation gives 60 planned pages. The output line displays that total. If the code were changed to add the values instead, the comment and variable names would need review.
Answer: The documentation is suitable because the purpose, names, and comment match the calculation and output.
Check: A later reader can tell what each input means and what total the program calculates.

Common mistakes and how to avoid them

Using names such as a, b, or x when the values have clear meanings.
Correction: Choose names that help a reader identify the value, such as ticket_count or pages_per_day.
Adding a comment that simply repeats an obvious instruction.
Correction: Use comments to explain purpose, meaning, or context that is not already clear from the code.
Leaving an old comment after changing the program.
Correction: Review comments whenever code changes and correct or remove details that no longer match.
Assuming comments make incorrect code correct.
Correction: Documentation helps readers understand code; check that the instructions and the explanation both match the intended task.

Lesson summary

  • Document a program so a later reader can understand its purpose and important details.
  • Use meaningful names and brief, useful comments.
  • Check that documentation matches the current code.
  • Trace the program's input, process, and output to see whether its purpose is clear.

Check your understanding

Question 1

Which comment is most useful above a calculation that multiplies the number of chairs by the cost of one chair?
  1. This program estimates the chair cost; the entered cost is for one chair.
  2. Multiply chairs by cost.
  3. The next line is a line of code.
  4. This program calculates the cost of tables.
Show answer and explanation
This program estimates the chair cost; the entered cost is for one chair.
It explains the purpose and clarifies what the cost value means. The other choices either repeat the visible operation, add no useful information, or describe a different task.

Question 2

A program now displays the total number of pages planned for five days, but its comment still says it displays the number of pages for one day. What should the programmer do?
  1. Leave the comment because comments do not affect the program.
  2. Update the comment so it accurately describes the current program.
  3. Delete the variable names so the comment stands out.
  4. Change the output to match the outdated comment without checking the task.
Show answer and explanation
Update the comment so it accurately describes the current program.
Documentation should match the current code and purpose. Although a comment does not change the program's instructions, an inaccurate comment can mislead a later reader.

Key terms

Documentation
Information written with or alongside a program to help people understand it.
Comment
A note in source code for a reader; in Python, a comment begins with #.
Input
Information a program receives.
Process
Work a program performs on its input.
Output
Information a program presents.

Continue through ICS2O

View the complete ICS2O Ontario Grade 10 Computer Science curriculum and lessons

Tutor support for B3.2 · Document a program for later readers

Working on B3.2 · Document a program for later readers in ICS2O? Bring the question and your own attempt. In a live session, you can trace a small input step by step, compare expected and actual output, and test an edge case. Ask about the first step that does not make sense, then try a similar question yourself.

Explore coding tutoring · Request an eligible free 30-minute introduction. Your request is matched by subject and language; a tutor must accept before a time is confirmed.

برای مبحث B3.2 · مستندسازی برنامه برای خوانندگان بعدی در درس ICS2O، سؤال و تلاش خود را همراه بیاورید. در جلسه می‌توانید یک ورودی کوچک را گام‌به‌گام دنبال کنید، خروجی مورد انتظار و واقعی را مقایسه کنید و یک حالت مرزی را بیازمایید. راهنمای معلم برنامه‌نویسی را ببینید یا جلسهٔ معارفهٔ رایگان ۳۰ دقیقه‌ای درخواست کنید. زمان جلسه پس از پذیرش معلم قطعی می‌شود.

About this lesson and its review

Published by DoAssignment. This reviewed lesson follows Ontario Grade 10 Computer Science (ICS2O), expectation B3.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.

Official curriculum reference

Report a correction or ask a question