Documentation CS Thinking Example 1
Follow the full solution, then compare it with the other examples linked below.
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.
Solution
- 1 Step 1: Comments explain the purpose and logic of code to human readers. They do not affect how the program runs.
- 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).
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).
About Documentation
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.
Learn more about Documentation →More Documentation Examples
Example 2 medium
List three types of software documentation and explain who each is written for.
Example 3 mediumA function has no comments or documentation. Reverse-engineer its purpose from the code: FUNCTION my
Example 4 hardArgue for and against the statement: 'Good code is self-documenting and does not need comments.' Whe