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

easy
Why are comments important in code? Add appropriate comments to this pseudocode: SET total = 0. FOR i = 1 TO 10: total = total + i. OUTPUT total.

Solution

  1. 1
    Step 1: Comments explain the purpose and logic of code to human readers. They do not affect how the program runs.
  2. 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. 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).

Answer

Comments explain purpose and logic. Good comments explain WHY code does something, not just WHAT it does.
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

medium
List three types of software documentation and explain who each is written for.

Practice Problems

Try these problems on your own first, then open the solution to compare your method.

Example 1

medium
A 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

hard
Argue for and against the statement: 'Good code is self-documenting and does not need comments.' When are comments essential despite good naming?
← Back to Documentation Practice Mode

Background Knowledge

These ideas may be useful before you work through the harder examples.

software development life cycle