Documentation Examples in CS Thinking
Start with the recap, study the fully worked examples, then use the practice problems to check your understanding of Documentation.
This page combines explanation, solved examples, and follow-up practice so you can move from recognition to confident problem-solving in CS Thinking.
Concept Recap
Software documentation is the collection of written descriptions that explain how a system works and how to use it, including inline code comments, user guides, API references, design documents, and README files. Good documentation makes software understandable, usable, and maintainable by both current and future developers.
Documentation is a letter to your future self (and teammates) explaining what the code does and why you made certain decisions.
Read the full concept explanation →How to Use These Examples
- Read the first worked example with the solution open so the structure is clear.
- Try the practice problems before revealing each solution.
- Use the related concepts and background knowledge badges if you feel stuck.
What to Focus On
Core idea: Code tells the computer what to do. Documentation tells humans why the code exists and how to use it.
Common stuck point: Don't document what the code does (the code itself says that). Document why it does it — the reasoning and decisions.
Sense of Study hint: When writing documentation, first explain the purpose (why does this code/module exist?). Then describe the interface (what inputs does it take and what does it return?). Finally, include usage examples that show the most common use cases in action.
Worked Examples
Example 1
easyWhy are comments important in code? Add appropriate comments to this pseudocode: SET total = 0. FOR i = 1 TO 10: total = total + i. OUTPUT total.
Answer
Comments explain purpose and logic. Good comments explain WHY code does something, not just WHAT it does.
First step
1
Step 1: Comments explain the purpose and logic of code to human readers. They do not affect how the program runs.
Full solution
- 2 Step 2: // Calculate the sum of numbers 1 to 10. SET total = 0 // Initialise accumulator. FOR i = 1 TO 10: total = total + i // Add each number to running total. OUTPUT total // Display the result (should be 55).
- 3 Step 3: Good comments explain WHY, not just WHAT. 'Add i to total' is a bad comment (restates the code). 'Accumulate sum for average calculation' is a good comment (explains purpose).
Documentation through comments makes code maintainable. Code is read far more often than it is written, so investing in clear comments saves time for future developers (including your future self).
Example 2
mediumList three types of software documentation and explain who each is written for.
Example 3
mediumName three types of software documentation and their audience.
Example 4
mediumDistinguish a TUTORIAL from a REFERENCE in documentation.
Example 5
mediumA function `calc(x)` has no doc. You read the code: it converts Celsius to Fahrenheit. Write a one-line docstring.
Example 6
hardYou inherit a 5,000-line module with no documentation. Outline a triage approach to document it without rewriting everything.
Example 7
hardArgue both sides: 'Good code is self-documenting and needs no comments.'
Example 8
hardA complex algorithm has a clever optimization. The code is short but baffling. What kind of documentation belongs alongside it?
Example 9
hardAn API's docs list every parameter but never give an example. What is the main risk?
Example 10
challengeYour team has open-source consumers of a library. You plan to deprecate a function in months. Design a 4-step documentation rollout to minimize user breakage.
Practice Problems
Try these problems on your own first, then open the solution to compare your method.
Example 1
mediumA function has no comments or documentation. Reverse-engineer its purpose from the code: FUNCTION mystery(text): SET result = ''. FOR i = LENGTH(text)-1 TO 0 STEP -1: result = result + text[i]. RETURN result. Write appropriate documentation for it.
Example 2
hardArgue for and against the statement: 'Good code is self-documenting and does not need comments.' When are comments essential despite good naming?
Example 3
easyWhich comment is BETTER: (a) 'x = x + 1 // add 1 to x' or (b) 'x = x + 1 // advance to next page'?
Example 4
easyWhat document typically tells a new user how to install and start using a project?
Example 5
easyWhat kind of documentation describes each function's parameters and return values for developers?
Example 6
easyDocumentation primarily serves which audience?
Example 7
easyTrue or false: documentation that is never updated as code changes (stale docs) can be worse than no docs.
Example 8
easyInline code comments belong WHERE?
Example 9
easyWhich is documentation: (a) a design document explaining architecture decisions, (b) the compiled binary?
Example 10
easyGood documentation explains code's ___ and how to use it, not just restating syntax.
Example 11
mediumA function has comments only for the success case; it can also throw on invalid input. What documentation gap exists?
Example 12
mediumA scenario: external developers integrate with your service via HTTP endpoints. Which doc type is most essential?
Example 13
mediumTwo comments: A='// loop' on a loop, B='// retry up to 3 times to tolerate transient network errors'. Which is good and why?
Example 14
mediumAfter a refactor, the README still shows the old command name. What is the defect and the fix category?
Example 15
mediumFor an end user (non-programmer) learning to use the app's features, which doc fits best?
Example 16
mediumA comment says '// returns true' but the function returns the count of items. What should be done?
Example 17
mediumWhich documentation set best supports a developer who must MAINTAIN unfamiliar code months later?
Example 18
mediumA new teammate needs to understand WHY a module exists and its overall structure, not call signatures. Which doc fits best?
Example 19
mediumA function's docstring lists parameters but omits that it returns null on error. What documentation principle is violated?
Example 20
challengeA team writes thorough docs once at launch but never updates them; six months later many are wrong. Name the failure and the disciplined fix.
Example 21
challengeA public library function changes its return type. Which docs MUST be updated to avoid breaking integrators, and why?
Example 22
challengeYou inherit code with no docs and cryptic logic. What documentation should you add FIRST to maximize future maintainability, and why?
Example 23
easyWhich is documentation: (a) the source file `parser.py`, (b) a `README.md` explaining how to run it?
Example 24
easyIs `getUserAddress()` better as a function name than `g()` from a documentation standpoint?
Example 25
easyA README typically lives at what location in a project?
Example 26
mediumWhich comment is more useful: (a) `// loop over users`, (b) `// skip suspended users to avoid sending re-engagement emails to banned accounts`?
Example 27
mediumA function takes a list, returns the list reversed. What four things should its docstring include?
Example 28
mediumA new engineer joins the team. Where should they look first to understand the project structure?
Example 29
mediumAuto-generated docs (e.g., from docstrings) have what main advantage over hand-written ones?
Example 30
mediumTrue or false: comments should explain code that is already obvious from the syntax.
Example 31
hardDocumentation gets out of date as code evolves. Name two engineering practices that combat doc drift.
Example 32
hardA 'breaking change' in a library release should be documented where most prominently?
Example 33
hardA team writes docs only after shipping. Suggest one process change that ties doc writing to code merging.
Related Concepts
Background Knowledge
These ideas may be useful before you work through the harder examples.
software development life cycle