Computer Science · 9th Grade · Programming with Purpose · Weeks 19-27

Documentation and Code Readability

Students will learn the importance of documentation in improving the usability of a code library.

• Common Core State Standards
• CSTA: 3A-AP-17
• CSTA: 3A-AP-18

About This Topic

Code is written once but read many times, by the original author returning after a break, by collaborators, and by future maintainers who may have no prior context. Documentation, including inline comments, docstrings, and clear variable names, bridges the gap between what code does mechanically and why it exists. For 9th graders, this is often the first time they encounter code as a form of professional communication, not just a set of instructions for a computer.

In US K-12 computer science, CSTA 3A-AP-17 and 3A-AP-18 ask students to document design decisions and make code accessible to others. This standard reflects real professional practice: in industry, undocumented code is a liability because it cannot be safely changed by anyone other than its original author. Students who internalize documentation as part of the coding process, rather than an afterthought, build a habit that makes every codebase they touch more maintainable.

Active learning is effective here because readability is inherently social. What seems clear to the author often requires effort from a reader. Peer review activities where students evaluate each other's documentation reveal the gap between perceived and actual clarity, creating specific and actionable feedback that self-assessment rarely produces.

Key Questions

1. Explain how documentation improves the usability of a code library.
2. Construct effective comments and docstrings for a given function.
3. Evaluate the readability of code with and without proper documentation.

Learning Objectives

• Explain how well-written documentation enhances the usability and maintainability of a code library.
• Construct clear and concise comments and docstrings for a given Python function, adhering to established conventions.
• Compare and contrast the readability and understandability of code snippets with and without adequate documentation.
• Evaluate the effectiveness of different documentation strategies in making code accessible to other programmers.

Before You Start

Introduction to Programming Concepts

Why: Students need a basic understanding of functions, variables, and control flow to comprehend what needs to be documented.

Basic Python Syntax

Why: Familiarity with Python syntax is necessary to write and understand code examples, comments, and docstrings.

Key Vocabulary

Documentation	Written explanations and information about a piece of software or code, intended to help users and developers understand its purpose, usage, and design.
Code Readability	The ease with which a human reader can understand the purpose, structure, and operation of source code.
Inline Comment	A note embedded directly within the source code, typically used to explain specific lines or blocks of code.
Docstring	A string literal that occurs as the first statement in a module, function, class, or method definition, used to document that object.
Maintainability	The ease with which software can be modified to correct defects, improve performance, or adapt to a changed environment.

Watch Out for These Misconceptions

Common Misconception

More comments always means better documentation.

What to Teach Instead

Comments that restate what the code obviously does add noise without adding clarity. A comment that says 'increment i by 1' next to 'i += 1' is redundant. Good documentation explains why, not what, and is targeted at the parts of the code where intent is not immediately obvious. Peer review quickly surfaces over-commenting.

Common Misconception

Documentation is something you add after the code is finished.

What to Teach Instead

Writing documentation alongside code, particularly docstrings before implementing a function, helps clarify the function's expected behavior before coding begins. Students who draft a docstring first frequently write cleaner code because the act of describing the function's purpose exposes design decisions they had not fully thought through.

Common Misconception

Only large projects with teams need documentation.

What to Teach Instead

Any code you might return to later, or share with anyone else, benefits from documentation. Students who work on individual projects often find that their own code is incomprehensible a week later without good documentation. Real experience with this during peer review is more persuasive than being told it matters.

Active Learning Ideas

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.

35 min·Pairs

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.

40 min·Pairs

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.

30 min·Small Groups

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.

20 min·Pairs

Real-World Connections

• Software developers at Google use extensive documentation for open-source libraries like TensorFlow, enabling millions of researchers and engineers worldwide to build AI applications.
• Game developers on teams creating titles like 'Fortnite' rely on clear code comments and documentation to collaborate effectively, ensuring that new features can be integrated without breaking existing gameplay.
• Open-source projects on platforms like GitHub, such as the Python language interpreter itself, depend heavily on community contributions to documentation, making the software accessible to a global audience of programmers.

Assessment Ideas

Peer Assessment

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

Quick Check

Present 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.

Discussion Prompt

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

Frequently Asked Questions

What is the difference between a comment and a docstring?

A comment is a note for any reader at a specific point in the code, usually explaining a non-obvious decision. A docstring is a standardized multi-line description attached to a function, class, or module that describes its purpose, parameters, and return value. Tools like Python's help() function can display docstrings, making them part of the code's usable interface.

What should go in a docstring?

A good docstring includes what the function does in one clear sentence, each parameter's name, type, and purpose, the return value and its type, and any exceptions or special cases the caller should know about. The goal is that someone can use the function correctly without reading its implementation.

How does active peer review improve documentation quality?

Documentation quality is invisible to the person who wrote the code because the author already knows what the code does. When a peer reads the same code cold and explains what they understand from the documentation alone, the author immediately sees which explanations were effective and which left gaps. This feedback is more precise than any rubric-based self-evaluation.

Do professional programmers actually write documentation?

Yes, and the absence of documentation is a recognized source of technical debt in industry. Most professional codebases have style guides that require docstrings for public functions and specify what types of comments are expected. Open-source projects typically decline contributions that add undocumented code, making documentation a professional baseline expectation.