Writing relevant and appropriate comments

Name:

Date:

Class:

Quick Questions

Shade in the A or B circle for each question.

1. Which comment is better for the line: Total ← Total + Price

A // Add the price of this item to the bill

B // Total becomes Total plus Price

2. Which comment explains WHY, not just what, for: IF Age < 13 THEN

A // Under 13s need a parent's permission

B // If Age is less than 13

3. Where should a comment be placed in this loop? FOR Count ← 1 TO 5 OUTPUT Count NEXT Count

A At the far left, whatever the code's indentation

B At the same indentation as the code it describes

4. A program has 10 lines. Which commenting approach is better?

A Put a comment on every single line, even obvious ones

B Comment only the sections or tricky steps that need explaining

5. Which comment is appropriate for the line: Remainder ← Number MOD 2

A // Find out if the number is odd or even

B // Declare a variable called Remainder

Match the Pairs

Draw a line connecting each item on the left to its match on the right.

Left column		Right column
1// Add 10% service charge to the bill Total ← Bill * 1.1		AA good comment that explains the purpose of the calculation, not just the symbols used
2// Stop once the user enters -1 WHILE Score <> -1		BFOR Count ← 1 TO 5 // Ask for one test mark INPUT Mark NEXT Count
3A comment should sit at the same indentation as the code it describes		C// Use MOD 2 to check if the number is even IF Number MOD 2 = 0 THEN
4A good comment explains why the code does something, not just what it does		DThe comment is not at the same indentation as the code it describes, so it is not clear which code it belongs to.
5// Set Total to 0 Total ← 0		EA comment that explains a non-obvious step, in this case the value that ends the loop
6WHILE Lives > 0 // Ask for a guess INPUT Guess ENDWHILE		FThe comment repeats the code word for word and adds no new information. A pointless comment like this just adds clutter.

Definitions

// explain purpose

Fill in the Blanks

Complete each line of code by filling in the missing parts.

__ Convert minutes into whole hours Hours ← Minutes DIV 60

IF Age < 0 THEN __ Age cannot be negative OUTPUT "Invalid age"

// Total cost including 10% tax TotalCost _ Price * 1.1

// Pass mark is 40 out of 100 ________ PassMark ← 40

// Average of three test marks Average ← (Mark1 + Mark2 + Mark3) / 3 ______ Average

Spot the Error

Shade in the letter of the line that contains an error.

Question 1

A CONSTANT VAT ← 0.2

B INPUT Price

C // Cost = Price * (1 + VAT)

D Cost ← Price * (1 + VAT)

Question 2

A DECLARE Score : INTEGER

B INPUT Score

C # Check if the student passed

D IF Score >= 50

E THEN

F OUTPUT "Pass"

Question 3

A FOR Count ← 1 TO 10

B INPUT Mark

C // Add Mark to Total

D Total ← Total + Mark

E NEXT Count

Question 4

A Total ← 0

B FOR Count ← 1 TO 5

C INPUT Mark

D // Reset the counter

E Total ← Total + Mark

F NEXT Count

Question 5

A INPUT Minutes

B Hours ← Minutes DIV 60

C Left ← Minutes MOD 60

D // OUTPUT the variables

E OUTPUT Hours, Left

Answer Key

Writing relevant and appropriate comments

Section A: Quick Questions

A — // Add the price of this item to the bill

A — // Under 13s need a parent's permission

B — At the same indentation as the code it describes

B — Comment only the sections or tricky steps that need explaining

A — // Find out if the number is odd or even

Section B: Match the Pairs

// Add 10% service charge to the bill Total ← Bill * 1.1 → A good comment that explains the purpose of the calculation, not just the symbols used

// Stop once the user enters -1 WHILE Score <> -1 → A comment that explains a non-obvious step, in this case the value that ends the loop

A comment should sit at the same indentation as the code it describes → FOR Count ← 1 TO 5 // Ask for one test mark INPUT Mark NEXT Count

A good comment explains why the code does something, not just what it does → // Use MOD 2 to check if the number is even IF Number MOD 2 = 0 THEN

// Set Total to 0 Total ← 0 → The comment repeats the code word for word and adds no new information. A pointless comment like this just adds clutter.

WHILE Lives > 0 // Ask for a guess INPUT Guess ENDWHILE → The comment is not at the same indentation as the code it describes, so it is not clear which code it belongs to.

Section C: Definitions

// explain purpose — A good comment explains why a section of code exists or a tricky step, without repeating the code word for word. Put it at the same indentation as the code it describes.

Section D: Fill in the Blanks

// Convert minutes into whole hours
Hours ← Minutes DIV 60

IF Age < 0 THEN
   // Age cannot be negative
   OUTPUT "Invalid age"

// Total cost including 10% tax
TotalCost ← Price * 1.1

// Pass mark is 40 out of 100
CONSTANT PassMark ← 40

// Average of three test marks
Average ← (Mark1 + Mark2 + Mark3) / 3
OUTPUT Average

Section E: Spot the Error

C — The comment just repeats the code in symbols, so it adds nothing. A good comment gives the purpose, for example // Work out the price with VAT.

C — Cambridge pseudocode comments start with //, not #. Without // the line is not a valid comment. It should be // Check if the student passed.

C — This comment only repeats the code below it word for word, so it explains nothing. A good comment gives the purpose: // Keep a running total.

D — The comment is misleading because the next line adds to Total and does not reset anything. A comment must match what the code does: // Add mark to the total.

D — This comment is vague and just names the command, so it explains no purpose. It should say why, for example // Show hours and minutes.