Code Comments
Write clear, useful comments in English — from inline WHY-comments to full JSDoc blocks and Python docstrings. 6 practice sets.
Reading Code Comments
Understand JSDoc, inline comments, and TODO/FIXME markers in real codebases.
Writing Inline Comments
Practise the "WHY not WHAT" rule — when to comment and how to phrase it clearly.
JSDoc & Docstrings
Write and fix JSDoc comment blocks: @param, @returns, @throws, @example.
Python Docstrings
Compare Google-style, NumPy-style, and Sphinx-style Python docstrings.
README Code Sections
Annotate code blocks and write clear Quick Start and installation sections.
Comment Quality
Spot anti-patterns (lying comments, obvious comments) and rewrite them correctly.
Quick reference
Comment types
- Inline comment: single-line explanation after/above code
- Block comment: multi-line explanation of a function or section
- Docstring: structured comment attached to a function/class (JSDoc, Python)
- TODO: planned future work ("TODO: add retry logic")
- FIXME: known bug or broken code to fix later
- HACK / XXX: temporary workaround; needs revisiting
- NOTE / NB: important contextual information
The "WHY not WHAT" rule
i++; // increment i— bad: says what the code doesi++; // skip the header row— good: says why- Comment on intent, not mechanics
- "We use X because Y" — provides context the code cannot show
- Document edge cases, non-obvious algorithms, external constraints
JSDoc key tags
@param {type} name - description@returns {type} description@throws {ErrorType} when …@example— usage example block@deprecated— marks a function as deprecated@see— cross-reference link