Activity 01
Peer Documentation Review
Students exchange programs with a partner who has not seen the code before. The reader attempts to explain, in plain English, what each function does and why specific decisions were made, using only the code and its documentation. The author notes where the reader's interpretation was wrong and revises the documentation to close the gap.
Explain how documentation improves the usability of a code library.
Facilitation TipFor Peer Documentation Review, assign pairs to evaluate each other’s comments against a simple rubric: explains why, avoids restating the obvious, targets unclear logic.
What to look forProvide students with two versions of a short Python function: one with minimal comments and one with comprehensive docstrings and inline comments. Ask students to read both and then answer: 'Which version is easier to understand and why? List three specific improvements made by the documentation in the second version.'
UnderstandApplyAnalyzeSelf-AwarenessRelationship Skills
Generate Complete Lesson→· · ·
Activity 02
Rewrite for Readability: Before and After
Provide pairs with an undocumented, poorly named version of a working program. They add docstrings, rename variables, and add comments, then compare their documentation choices with another pair and discuss disagreements about what deserves a comment versus a rename.
Construct effective comments and docstrings for a given function.
Facilitation TipFor Rewrite for Readability, provide a short, messy code snippet and give students exactly 10 minutes to draft a clearer version with improved names and comments before they see the improved model.
What to look forPresent students with a function and ask them to write a docstring that explains its purpose, parameters, and return value. Then, have them add at least two inline comments to clarify complex logic within the function body.
UnderstandApplyAnalyzeSelf-AwarenessRelationship Skills
Generate Complete Lesson→· · ·
Activity 03
Gallery Walk: Documentation Quality Spectrum
Post six code samples ranging from no documentation to over-commented, with good documentation in the middle range. Students rank them from most to least readable, annotating what makes each level more or less useful. Class discussion identifies patterns in what constitutes helpful versus unhelpful documentation.
Evaluate the readability of code with and without proper documentation.
Facilitation TipFor Gallery Walk, post three versions of the same function around the room: minimal comments, over-commented, and well-balanced; have students annotate which version they would prefer to maintain and why.
What to look forFacilitate a class discussion using the prompt: 'Imagine you are taking over a project from a developer who left the company without any documentation. What are the biggest challenges you would face, and how could good documentation have prevented them?'
UnderstandApplyAnalyzeCreateRelationship SkillsSocial Awareness
Generate Complete Lesson→· · ·
Activity 04
Think-Pair-Share: Comment or Rename?
Present ten code snippets, each with a clarity problem. For each, students decide whether the fix is a comment explaining the logic or a variable/function rename that makes the logic self-evident. Pairs compare choices and discuss the principle behind each decision.
Explain how documentation improves the usability of a code library.
What to look forProvide students with two versions of a short Python function: one with minimal comments and one with comprehensive docstrings and inline comments. Ask students to read both and then answer: 'Which version is easier to understand and why? List three specific improvements made by the documentation in the second version.'
UnderstandApplyAnalyzeSelf-AwarenessRelationship Skills
Generate Complete Lesson→A few notes on teaching this unit
Experienced teachers approach this topic by treating code readability as a form of professional writing, not just technical correctness. They begin with short, relatable code snippets students can fully grasp in under a minute, so cognitive load is on communication, not algorithmic complexity. They also model their own thinking aloud when they revise code, showing that clarity is a skill honed through iteration, not innate talent.
By the end of these activities, students will consistently write docstrings that explain a function’s purpose, parameters, and return value, and they will add inline comments only where the intent is not obvious. They will also recognize over-commenting and redundant variable names during peer review and revise their own work accordingly.
Watch Out for These Misconceptions
During Peer Documentation Review, watch for students who believe more comments always means better documentation.
Use the peer review rubric to guide students to distinguish between comments that explain intent and those that repeat the code. During the activity, circulate and point to specific examples where a comment restates the obvious, then ask the class to suggest a clearer alternative together.
During Rewrite for Readability, watch for students who see documentation as a post-coding task.
Before they start writing, have students draft a docstring first, then use it to guide their implementation. After the activity, ask them to reflect on how writing the docstring early changed the clarity of their code and variable choices.
During Gallery Walk, watch for students who think only large team projects need documentation.
After viewing the three versions, pose a scenario: 'You wrote this code last night and need to fix a bug tomorrow morning.' Ask students to vote on which version they’d prefer to revisit, then discuss how even individual projects benefit from clear documentation.
Methods used in this brief