Documentation & Program Readability

You’ll be able to

Explain the purpose and audience of program documentation and comments
Distinguish documentation from the code it describes
Use meaningful names and comments to make a program maintainable

What documentation is for

Documentation is written description that explains what a program does and how to use or modify it. It serves two audiences: users, who need to know what the program does and how to operate it, and developers (including your future self), who need to understand the code well enough to fix or extend it. Because programs are developed iteratively and often over long spans of time, documentation is what lets a program be maintained after the original author has forgotten the details — or moved on entirely.

Comments: notes inside the code

A comment is a note written in the source code that the computer ignores when running the program — it exists purely for human readers. Good comments explain the why and the intent behind a section of code, not the obvious what. A comment like // add 1 to x beside x ← x + 1 is useless; a comment like // advance to the next student in the roster tells a reader something the code alone does not. Comments describe purpose, document assumptions, and flag anything tricky.

Readable code documents itself

The best documentation is often the code itself, made clear through meaningful names. A variable named totalScore needs no comment; one named x does. Descriptive names for variables and procedures let the code read almost like a description of what it does. Combined with sensible structure — breaking a big task into well-named procedures — good naming reduces how many comments you even need. Documentation and readable code work together to make a program maintainable: understandable and safely changeable over time.

Worked example

Compare these two lines of AP pseudocode. Which is better documented, and why? Version A: n ← n * 1.08 Version B: // apply the 8% sales tax to the running total total ← total * 1.08

1.Version A uses the vague name n and has no comment, so a reader cannot tell what the multiplication represents or why the number is 1.08.
2.Version B renames the variable to total, which signals what the value is, and adds a comment explaining the why — that 1.08 applies an 8% tax.
3.A future developer reading Version B instantly understands the purpose; reading Version A, they would have to guess.

Answer: Version B is better documented. The meaningful name total makes the code self-explanatory, and the comment records the intent (an 8% sales tax) that the bare number 1.08 does not reveal. Together they make the line maintainable.

Checkpoint

Which comment adds the most useful documentation to the line `count ← count + 1`?

Watch out

A comment that just repeats the code ("add 1 to x") is clutter, not documentation. Useful comments explain why and intent — the things the code cannot say for itself.

Checkpoint

Why is thorough documentation especially important for a program that will be maintained by a team over several years?

On the exam

For the Create Performance Task you must write comments identifying key components of your program. Comments and meaningful names are graded parts of the artifact — treat documentation as part of the program, not an afterthought.

Answer the 2 checkpoints as you read.