Purpose of a code segment (College Board AP® Computer Science Principles): Revision Note
Documentation types & practices
Why is documentation important?
Documentation is written information that describes how the code was developed, what a program or section of code does, how it works, and how it should be used
Documentation is completed throughout development
Documentation supports the development process by helping team members understand each other's code
It aids maintenance: when a program needs to be updated or fixed, clear documentation helps developers understand the original intent without reading every line in detail
Good documentation improves correctness by making the intended behavior of the code explicit, reducing the risk of misinterpretation
Not all programming environments support comments, so other methods of documentation (such as external documents or separate readme files) may be needed
What documentation can describe
What's documented | Description | Example |
|---|---|---|
A code segment | A portion of the program — a block of statements that work together | A comment above a loop explaining what it calculates |
An event | An action that triggers code to run, such as a button click or key press | A note describing what happens when the user clicks "Submit" |
A procedure | A named group of instructions that may take inputs and return a result | A comment above a function listing its parameters and what it returns |
A program | The whole piece of software | An overview at the top of the file summarizing what the program does |
Comments are the most common form of in-code documentation and are ignored by the computer during execution
Documentation should be kept up to date: outdated comments can be more misleading than no comments at all
Examiner Tips and Tricks
Comments are for human readers — they do not affect how the program runs. If the AP exam asks about the purpose of a comment, focus on what it communicates to a developer, not what it makes the computer do.
While documenting your code with comments is a best practice and is required in your Full Program Code submission to acknowledge code written by others or generated by AI, you must remove all comments before taking screen captures for your Personalized Project Reference (PPR).
If your PPR screen captures contain any comments or course content, you will not be able to use it on exam day and you will receive an automatic score of 0 for the written response portion of the Create Performance Task.
Worked Example
A developer is working on a large program with a team. Throughout development, she writes comments explaining what each procedure does and how it was built.
Which of the following best describes why this is a good practice?
(A) The comments make the program run faster by optimizing each procedure
(B) The comments help team members understand the code when developing and maintaining the program
(C) The comments act as a backup copy of the code in case files are lost
(D) The comments prevent other developers from modifying her procedures
[1]
Answer:
(B) The comments help team members understand the code when developing and maintaining the program [1 mark]
Documentation, including comments, helps in developing and maintaining correct programs when working individually or in collaborative environments (CRD-2.G.4). Comments are ignored by the computer during execution, so they do not affect speed (ruling out A), and they are not backups or access controls (ruling out C and D).
Unlock more, it's free!
Join the 100,000+ Students that ❤️ Save My Exams
the (exam) results speak for themselves:
Was this revision note helpful?
