Computer Science · Grade 10

Active learning ideas

Documentation and Code Comments

Active learning strengthens students' ability to communicate technical ideas when documentation and comments feel abstract. These activities transform passive reading into collaborative writing, where students experience firsthand how clear explanations save time and reduce frustration in team projects.

• Ontario Curriculum Expectations
• CS.HS.D.10
• CS.HS.D.11

• 30–45 min
• Pairs → Whole Class
• 4 activities

Activity 01

• Peer Teaching
• 35 min · Pairs

Pair Programming: Comment Relay

Pairs alternate writing code for a simple function, like a sorting algorithm, then switch to add comments explaining logic without seeing the partner's notes. They review together, refining comments for clarity. End with a class share-out of best examples.

Explain the purpose of internal and external documentation in software projects.

Facilitation Tip

During Pair Programming: Comment Relay, sit nearby to listen for pairs negotiating which parts of the code need the most explanation.

What to look for

Present students with a short, uncommented code snippet containing a simple loop or conditional statement. Ask them to write one concise inline comment explaining its purpose. Review responses for accuracy and clarity.

• Understand
• Apply
• Analyze
• Create
• Self-Management
• Relationship Skills

Activity 02

• Peer Teaching
• 45 min · Small Groups

Group README Build

Small groups extend a starter project by drafting a full README: installation steps, usage examples, and contributor guidelines. They test docs by having another group follow them blindly. Revise based on feedback.

Construct effective code comments that clarify complex logic.

Facilitation Tip

For Group README Build, provide a template with headings but no content to reduce decision fatigue for struggling writers.

What to look for

In pairs, students review each other's small code projects. They use a checklist to assess: Are there comments explaining variables? Is the main logic of functions commented? Is there a basic README file? Partners provide one specific suggestion for improvement.

• Understand
• Apply
• Analyze
• Create
• Self-Management
• Relationship Skills

Activity 03

• Peer Teaching
• 40 min · Small Groups

Code Review Stations

Set up stations with anonymized student code snippets lacking comments. Groups rotate, adding targeted comments and notes on improvements. Debrief as a class on common patterns.

Justify the importance of good documentation for future developers and users.

Facilitation Tip

At Code Review Stations, rotate roles so each student practices both giving and receiving feedback on documentation quality.

What to look for

Ask students to write two sentences: 1. What is the primary difference between inline comments and a README file? 2. Name one way good documentation helps a developer who is new to a project.

• Understand
• Apply
• Analyze
• Create
• Self-Management
• Relationship Skills

Activity 04

• Peer Teaching
• 30 min · Individual

Documentation Sprint

Individuals time themselves commenting a provided complex script in 10 minutes, then pairs merge and optimize comments. Share top versions whole class.

Explain the purpose of internal and external documentation in software projects.

Facilitation Tip

In Documentation Sprint, set a visible timer so students experience the tension between speed and thoroughness.

What to look for

Present students with a short, uncommented code snippet containing a simple loop or conditional statement. Ask them to write one concise inline comment explaining its purpose. Review responses for accuracy and clarity.

• Understand
• Apply
• Analyze
• Create
• Self-Management
• Relationship Skills

A few notes on teaching this unit

Teach documentation as a habit, not a task, by modeling your own commenting process aloud during live coding. Avoid assigning documentation after the fact, as students will rush through it. Research shows that students improve most when they see peers struggle to understand unclear code, so design activities where the audience is real classmates, not just the teacher.

By the end of these activities, students will produce documentation that peers can use to understand, modify, and extend their code without prior explanation. Success looks like comments that answer 'why' rather than 'what,' READMEs that orient new users in under two minutes, and feedback that improves clarity.

---

Watch Out for These Misconceptions

• During Pair Programming: Comment Relay, students may assume the driver should comment every line as they type.

  Remind students that comments should explain non-obvious decisions, not the code itself. Pause the relay after two minutes to highlight examples where comments added clarity about design choices rather than mechanics.

• During Group README Build, students might write long paragraphs assuming readers already know the project.

  Direct groups to test their README on a classmate from another group after 15 minutes. If the reader cannot explain the project’s purpose in one sentence, the team returns to revise for conciseness and clarity.

• During Documentation Sprint, students believe inline comments and READMEs serve the same purpose.

  Hold a mini-debate where teams argue which audience each type serves. Use examples from their own projects to show how READMEs answer 'what can this do?' while comments answer 'how does this work?'.

---

Methods used in this brief

• Peer Teaching