Practice & Assessment
Test your understanding of Code Comments and Inline Documentation
Multiple Choice Questions
5Which comment adds the most value?
In a JSDoc comment, what does @throws document?
When should you write a module-level README in a monorepo?
What is the purpose of an Architecture Decision Record (ADR)?
What is the key discipline when using automated documentation generation tools like TypeDoc or Sphinx?
Coding Challenges
1Add Complete JSDoc to an Undocumented JavaScript Module
You are given a JavaScript file with 4 exported functions: createSession, validateToken, refreshToken, and revokeSession. Each function has 2–4 parameters, returns a Promise, and can throw 2 specific error types. Input: the undocumented source file. Task: add complete JSDoc comments to all 4 functions including: one-sentence description, @param with type and constraint for every parameter, @returns with Promise resolution type documented, @throws for every error type with trigger condition, and one @example per function with realistic data and expected output. Output: the updated JavaScript file. Estimated time: 20–25 minutes.
Mini Project
Document a Real Codebase Module
Take a real open-source JavaScript or Python project from GitHub with poor inline documentation. Pick one module or file with at least 5 public functions. Deliver: (1) the original file for reference, (2) the fully documented version with JSDoc or Python docstrings on every public function — description, all parameters with types and constraints, return type, all thrown exceptions; (3) a module-level README covering what the module owns, what it does not own, and local setup; (4) one Architecture Decision Record for the most non-obvious design choice in the module, documenting the context, decision, and at least two alternatives considered. All in a single PR-style Markdown diff document.