1.3 Documentation and acknowledgmentNotes for people, and credit where it's due

Program documentation is a written description of the function of a code segment, event, procedure or program, and of how it was developed. Comments are a form of documentation written into the program itself, to be read by people. Here's the fact the exam tests most: comments do not affect how a program runs. The computer skips them completely.
1// tipShare: one person's share of a bill, tip included12// percent is a whole number, like 20 for 20 percent13PROCEDURE tipShare(bill, people, percent)4{5 tip ← bill * percent / 1006 // split idea from Dana R. (pair partner), used with credit27 RETURN((bill + tip) / people)8}
- line 1-2 Says what the procedure does and what its input means
- line 6 Credits code that came from someone else
?Wait, if the computer ignores comments, why bother?
Programmers should document a program throughout its development, not all at the end, when they have forgotten why they made each choice. Documentation helps in developing and maintaining correct programs, whether you work alone or on a team. And not every programming environment supports comments (some block-based tools, for example), so sometimes documentation has to live somewhere else, like a separate design document or notes attached to the project.
Acknowledging other people's code
It is perfectly fine, and normal, to use code that someone else wrote. Professionals do it all day. What isn't fine is presenting it as your own. Any code segment developed collaboratively or by another source must be acknowledged, and the acknowledgment should include where it came from or the original author's name, in the program documentation. That includes code from a classmate, a tutorial, a library, a website, or a generative AI tool.
?Wait, what's the PPR?
I thought about it. Show me
- (a) "// Returns one person's share of the bill, tip included. percent is a whole number: 20 means 20 percent."
Why?
The most useful comment tells a caller what the procedure does and what each input means. Without it, someone might pass 0.2 instead of 20. - (b) "// Rounding to the nearest cent written by Sam (team member), used with credit."
Why?
An acknowledgment names the origin or the original author. - (c) They help a teammate use and maintain the procedure correctly, and give fair credit. They do not change what the program does or make it run any faster.
Why?
This is the pairing the exam tests: comments help people, not the computer.
Answer: A comment such as "Returns one person's share, tip included; percent is a whole number like 20", plus "Rounding written by Sam (team member)". They help people use, change and credit the code. They do not change how it runs.
Stuck? Get a hint
- What would a teammate need to know to call tipShare without reading every line?
- An acknowledgment says who wrote it or where it came from.
- Does the computer do anything with a comment?
- AChange the variable names so the code is hers
- BUse it, and acknowledge the tutorial as the source in her program documentation
- CUse it without credit, since tutorials are public
- DNever use code from outside sources in any program
Show the answer
B. Code from another source can be used, but it must be acknowledged with its origin or author. Renaming variables is the trap: it doesn't change who wrote the code. (Remember too that her written responses should be about code she wrote herself.)
Two facts about comments appear on the exam again and again: they help people understand and maintain code, and they never change how the program runs. If an answer choice says comments make a program faster, more correct, or able to run, it's wrong.
- Documentation describes what code does and how it was developed. Comments are documentation inside the code.
- Comments are for people. They do not affect how the program runs.
- Document throughout development. Some environments don't support comments, so use other documentation.
- Acknowledge any code from another source, with its origin or author's name.