Documentation CS Thinking Example 4
Follow the full solution, then compare it with the other examples linked below.
Example 4
hardArgue for and against the statement: 'Good code is self-documenting and does not need comments.' When are comments essential despite good naming?
Solution
- 1 Step 1: For: well-named variables and functions (calculateTax, isValidEmail) reduce the need for comments. Comments that restate code (// add 1 to x) add clutter.
- 2 Step 2: Against: comments are essential for explaining WHY (business rules, workarounds), complex algorithms, and non-obvious side effects. 'Self-documenting' code cannot explain why a particular approach was chosen over alternatives.
- 3 Step 3: Best practice: use clear naming to make WHAT the code does obvious, use comments to explain WHY it does it that way.
Answer
Good naming reduces need for comments, but comments are essential for explaining WHY, business logic, and complex algorithms. Use both.
The debate about comments is ongoing in software engineering. The consensus is that naming explains WHAT, comments explain WHY, and both are needed for maintainable code.
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 3 mediumA function has no comments or documentation. Reverse-engineer its purpose from the code: FUNCTION my