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.

• Grade 10
• Computer Science
• 4 activities
• 30 min–45 min

Learning Objectives

1. Analyze the impact of poorly documented code on project timelines and team collaboration.
2. Create inline code comments that accurately explain variable usage, complex algorithms, and function purposes.
3. Design a README file that effectively communicates a project's purpose, setup instructions, and usage guidelines.
4. Evaluate the quality of code comments and external documentation based on clarity, conciseness, and completeness.
5. Justify the necessity of both internal and external documentation for software maintainability and scalability.

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.

Prepare & details

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.

Setup: Presentation area at front, or multiple teaching stations

Materials: Topic assignment cards, Lesson planning template, Peer feedback form, Visual aid supplies

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

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.

Prepare & details

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.

Setup: Presentation area at front, or multiple teaching stations

Materials: Topic assignment cards, Lesson planning template, Peer feedback form, Visual aid supplies

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

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.

Prepare & details

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.

Setup: Presentation area at front, or multiple teaching stations

Materials: Topic assignment cards, Lesson planning template, Peer feedback form, Visual aid supplies

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

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.

Prepare & details

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.

Setup: Presentation area at front, or multiple teaching stations

Materials: Topic assignment cards, Lesson planning template, Peer feedback form, Visual aid supplies

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

Teaching This Topic

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.

What to Expect

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

Common Misconception

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

What to Teach Instead

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.

Common Misconception

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

What to Teach Instead

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.

Common Misconception

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

What to Teach Instead

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?'.

Assessment Ideas

Quick Check

After Pair Programming: Comment Relay, display three sample snippets with varying comment quality. Ask students to vote on which snippet would be easiest to modify and explain why the comments helped or hindered understanding.

Peer Assessment

During Code Review Stations, partners use a checklist to score each other’s README on: clarity of purpose, installation steps, and example usage. Collect these scores to identify common gaps in external documentation.

Exit Ticket

After Documentation Sprint, ask students to write one thing they learned about their own documentation habits and one change they plan to make next time, focusing on either inline comments or the README.

Extensions & Scaffolding

• Challenge students to add a troubleshooting section to their README after testing their code with a partner.
• Scaffolding: Provide a partially filled README template with guiding questions for each section.
• Deeper exploration: Invite students to compare two open-source projects of similar size, analyzing which documentation style they find more helpful.

Key Vocabulary

Inline Comment	A note within the source code, typically starting with a specific symbol (like // or #), used to explain a particular line or block of code.
External Documentation	Information about a software project that exists outside of the source code itself, such as README files, user manuals, or API specifications.
README File	A standard text file included in a software project's root directory that provides essential information for users and developers, including project description, installation, and usage.
Code Maintainability	The ease with which software can be modified, corrected, or enhanced. Good documentation significantly improves maintainability.
API Documentation	Detailed explanations of how to use an Application Programming Interface (API), including available functions, parameters, and return values.