Teaching documenting computer programs in grade 7 does not have to be complicated. Picture a software engineer documenting code so teammates and future maintainers can understand and safely modify it. That kind of thinking is exactly what Oklahoma's grade 7 computer science standard 7.AP.PD.05 asks students to practice \u2014 and it is very teachable with the right materials. This post walks through what the standard means, the misconceptions students bring to it, and discussion starters you can use tomorrow, whether you teach in a classroom or at your kitchen table.<\/p>\n
\nDocument text-based programs of increasing complexity in order to make them easier to follow, test, and debug.\n\u2014 Oklahoma Academic Standards for Computer Science (February 2023)<\/em><\/p>\n<\/blockquote>\n
In plain language: Oklahoma's standard asks seventh graders to document text-based programs of increasing complexity in order to make them easier to follow, test, and debug.<\/p>\n
In student-friendly terms, the learning target is: "I can document text-based programs of increasing complexity in order to make them easier to follow, test, and debug."<\/strong><\/p>\n
What Students Should Be Able to Do<\/h2>\n
\n
- I can write clear comments explaining what code sections do and why.<\/li>\n
- I can use descriptive variable names that reflect what they represent.<\/li>\n
- I can adapt my documentation to a program's growing complexity.<\/li>\n
- I can explain how documentation makes a program easier to test and debug.<\/li>\n<\/ul>\n
Along the way, students pick up the working vocabulary of the topic: documentation, comment, variable, descriptive, follow, debug, complexity, overview, maintain, readability, consistent, changelog.<\/p>\n
Documenting Computer Programs: Misconceptions to Watch For<\/h2>\n
These are the wrong turns students reliably take with this standard \u2014 knowing them ahead of time is half the lesson plan. Each correction strategy below comes straight from the unit's teacher guide (the paragraph and activity references point into the unit itself).<\/p>\n
1. "Documentation matters less as a program becomes more complex, since there's less time to write it."<\/strong><\/p>\n
Use paragraph 1's key point \u2014 documentation becomes more important, not less, as complexity grows, since it's harder to remember how everything works.<\/p>\n
2. "A comment is processed by the computer along with the rest of the code."<\/strong><\/p>\n
Reference paragraph 2 \u2014 comments are ignored by the computer entirely and exist only to be read by humans.<\/p>\n
3. "Variable names don't really matter as long as the code technically works correctly."<\/strong><\/p>\n
Point to paragraph 3 \u2014 descriptive variable names function as a quiet, built-in form of documentation that helps readers follow logic naturally.<\/p>\n
4. "Once documentation is written, it never needs to be updated again."<\/strong><\/p>\n
Clarify from paragraph 8 \u2014 documentation should be kept accurate and up to date as a program changes, since outdated notes can mislead readers.<\/p>\n
Discussion Starters You Can Use Tomorrow<\/h2>\n
\n
- Why do you think programmers sometimes skip writing documentation, even though it's genuinely helpful?<\/li>\n
- What's an example of a vague variable name you could rewrite to be more descriptive?<\/li>\n
- Why might a tester benefit from documentation before even running a program?<\/li>\n<\/ul>\n
Bringing It Home<\/h2>\n
This topic is a natural one for families. One ten-minute activity to try: Together, look at a recipe, instruction manual, or set of directions and discuss what makes it clear or confusing, then talk about how that relates to writing clear notes in a computer program.<\/p>\n
Where This Leads<\/h2>\n
Students who can document text-based programs of increasing complexity in order to make them easier to follow, test, and debug are building skills used every day in software engineering, technical writing, open source maintenance, QA testing, and computer science education.<\/p>\n\n
See the Unit in Action<\/h2>\n\n