Documentation CS Thinking Example 3
Follow the full solution, then compare it with the other examples linked below.
Example 3
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.
Solution
- 1 Step 1: The function iterates through the string backwards, building a new string character by character. It reverses the input string.
- 2 Step 2: Documentation: // FUNCTION reverseString(text): Reverses the input string. // Parameter: text (String) - the string to reverse. // Returns: String - the input string with characters in reverse order. // Example: reverseString('hello') returns 'olleh'.
Answer
The function reverses a string. Documentation should include: purpose, parameters, return value, and an example.
Good function documentation describes purpose, parameters, return value, and examples. This allows other developers to use the function without reading its implementation.
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 1 easy
Why are comments important in code? Add appropriate comments to this pseudocode: SET total = 0. FOR
Example 2 mediumList three types of software documentation and explain who each is written for.
Example 4 hardArgue for and against the statement: 'Good code is self-documenting and does not need comments.' Whe