← VCE Applied Computing U1O2

Explaining data and code structures with comments

A comment beside a variable, list, record or class that says what it stores and how it is used, so other programmers can understand the data and code structures.

Part of: VCE Applied Computing U1O2 Programming: Naming conventions and internal documentation — Module 7, QCE Digital Solutions Unit 1 — Algorithms and Programming Techniques — Module 96, QCE Digital Solutions Unit 1 — Programmed Solutions — Module 120, QCE Digital Solutions Unit 4 — Complex Digital Data Exchange Problems and Solution Requirements — Module 138

Understanding Explaining data and code structures with comments in VCE Applied Computing U1O2

What it does: The comment tells the reader this attribute stores a test mark and that its scale is out of 100. The comment explains the purpose of the loop, so the reader understands how the data structure is being used. Placing the comment next to the variable's declaration helps other programmers understand it as soon as they see it. Comments on records should say what each field stores. Vague wording like 'thing' does not help another programmer. The better comment explains what the attribute represents and its unit. The other one only repeats what the code already shows. The computer ignores comments, but people rely on them. A wrong comment is worse than none because it misleads maintainers.

Common mistakes: Python comments start with #, not //. The // is a syntax error. It should be scores = [] # student marks. The comment is misleading. len(ages) counts how many values are in the list, it does not add them up. The comment should say how many ages.

Class: _____________________ · Name: _____________________ · Date: _________

Free printable worksheet with full answer key — or add this module to a class and your students practise it interactively.

🖨 Print worksheet + answer key Add Explaining data and code structures with comments to a class →

This module's key terms are also in a printable crossword (Modules 89–124) and word search (Modules 8–124).

Take this worksheet further — free with Cloodit

Each concept is reinforced from every angle — learned, then applied, then tested.

Learning

Duo

Which comment best explains this list? scores = []

scores = [] # marks for each student in Class 10Ascores = [] # a list

Matches

scores = [] # list

↓

The comment only repeats the data type. It does not say what the list stores (marks for each student) or how it is used.

Applying

Meanings

Term

scores = [] # marks for each student

Meaning

A comment beside a variable, list, record or class that says what it stores and how it is used, so other programmers can understand the data and code structures.

Practice

scores = [] # marks for each student

Testing

Gaps

scores = [] marks for each student

Check Answer

Spots

1scores = [] // student marks

2scores.append(85)

Cloodit turns curriculum-aligned coding content into journeys students work through one biome at a time.

Students earn collectable badges

Over 100 of them, across seven natural biomes.

Study Buddy

Students build a real study resource

Turns their work into revision material ready for Flash Cards and Exam study.

Diamond Dash — one of Cloodit's live, competitive Sprint games

Students lock in with Sprints

Live, competitive practice for the start of the lesson or a teacher-led lesson finisher.

A Cloodit certificate of achievement, ready to personalise and print

Custom printable certificates

Honour your top performers, or encourage a student who's trying hard — ready to print in seconds.

Add to class →

Quick Questions

1. Which comment best explains this list? scores = []

A. scores = [] # marks for each student in Class 10A ✓

B. scores = [] # a list

A good comment says what the data stores, not just what type it is. The code already shows that scores is a list.

2. Where is the best place for a comment that describes what a variable stores?

A. Beside the variable where it is created ✓

B. Hidden at the very end of the program

Placing the comment next to the variable's declaration helps other programmers understand it as soon as they see it.

3. Which comment helps a maintainer understand this record? student = {"name": "Ava", "year": 10}

A. # this is where I make the student thing

B. # student record: name is full name, year is year level ✓

Comments on records should say what each field stores. Vague wording like 'thing' does not help another programmer.

4. Which comment is most useful above this class attribute? self.balance = 0

A. # balance: dollars currently held in the account ✓

B. # sets balance to zero

The better comment explains what the attribute represents and its unit. The other one only repeats what the code already shows.

5. Which comment correctly explains a loop? for mark in scores: total += mark

A. # this loop is very clever and fast

B. # add each student's mark to the running total ✓

A loop comment should explain its purpose in the program. Opinions about the code are not documentation.

Match the Pairs

scores = [] # marks for each student → A comment beside a list that says what data it stores

class Student: # one student's record → A comment beside a class that explains what the class represents

A comment on an attribute states what it stores and its unit or range → self.mark = 0 # test mark out of 100

A comment on a loop explains what the loop does and why → for s in scores: # add each mark to total

scores = [] # list → The comment only repeats the data type. It does not say what the list stores (marks for each student) or how it is used.

scores = [] // marks for each student → Python comments start with #, not //. The // symbol is a syntax error here, so the comment is not valid.

Key Term

scores = [] # marks for each student

A comment beside a variable, list, record or class that says what it stores and how it is used, so other programmers can understand the data and code structures.

Fill in the Blanks

1. scores = [] # marks for each student

Hint: Type the symbol that starts a Python comment explaining what the list stores.

2. class Student: # one student and their mark def __init__(self, mark):

Hint: Type the keyword that defines a new class.

3. # add every mark to the running total for mark in scores: total = total + mark

Hint: Type the keyword that starts a loop repeating over each item in the list.

4. # pass if the mark is 50 or more if mark >= 50: print("Pass")

Hint: Type the comparison operator meaning greater than or equal to.

5. class Student: # stores one student's mark out of 100 mark = 0

Hint: Type the symbol that begins a comment explaining what the class attribute stores.

Spot the Error

Question 1

A scores = [] // student marks

B scores.append(85)

C print(scores)

Line A — Python comments start with #, not //. The // is a syntax error. It should be scores = [] # student marks.

Question 2

A ages = [14, 15, 14]

B total = sum(ages)

C n = len(ages) # total of ages

D print(total / n)

Line C — The comment is misleading. len(ages) counts how many values are in the list, it does not add them up. The comment should say how many ages.

Question 3

A class Player:

B stores a player's score

C score = 0

Line B — The comment line is missing the # symbol, so Python tries to run it as code and gives a syntax error. It should start with #.

Question 4

A marks = [70, 85, 60]

B total = 0

C for m in marks:

D total += m # print a mark

Line D — The comment does not match what the loop does. total += m adds each mark to the total, it does not print anything. The comment should say add a mark.

Question 5

A s = {} # one student record

B s['name'] = 'Ava' # mark

C s['mark'] = 88 # mark

Line B — The comment says mark but this key stores the student's name. A comment beside a record field must say what that field stores, so it should be # name.

Student with a class code? Join your class →