Practice & Assessment
Test your understanding of Comments and Documentation Done Right
Multiple Choice Questions
6Which of these is an example of a comment that should be written?
What is 'comment rot'?
What is the main job of a project README?
A TODO comment is most useful when it includes:
What does a commit message body (as opposed to the subject line) explain?
Which functions should have JSDoc or docstring documentation?
Coding Challenges
1Comment Audit and JSDoc Addition
You are given a JavaScript utility library (utils.js) containing 15 functions with a mix of noise comments, missing documentation on public functions, 8 undescribed TODO comments, and 2 outdated comments that contradict the current code. Input: the provided utils.js file. Output: cleaned-utils.js where all noise comments are deleted, all public functions have proper JSDoc with @param, @returns, and any edge case notes, all TODOs are updated to include owner placeholder, ticket placeholder, and action description, and all outdated comments are corrected or removed. Estimated time: 25 minutes.
Mini Project
Documentation Kit for an Undocumented API
You are given a REST API with 12 endpoints across 3 resources (users, products, orders) that has zero documentation. Your task: write a complete README.md with one-line project description, quick start commands, and full environment variable table; add JSDoc to every exported function in the codebase; write conventional commit messages for 5 example changes as a COMMIT_EXAMPLES.md file; convert all 11 existing TODO comments to the owner-ticket-action-urgency format with a placeholder for each field; and write a COMMENTS_GUIDE.md explaining to future contributors when to comment and when to rely on code clarity. No application logic changes.