Engineering Craft › Documentation & Writing
Docstrings / JSDoc
Documenting functions and modules right next to the code.
Also known as: docstring, JSDoc, inline documentation, API docs comments
Code documentation means documenting functions, classes and modules right next to the code, in a format that tools can turn into help text and reference pages.
def apply_discount(price: float, percent: float) -> float:
"""Return price reduced by percent.
Args:
price: the original price, in the shop's currency.
percent: a discount from 0 to 100.
Raises:
ValueError: if percent is outside 0-100.
"""/**
* Returns the price reduced by a percentage.
* @param {number} price - original price
* @param {number} percent - discount from 0 to 100
* @returns {number}
* @throws {RangeError} if percent is outside 0-100
*/
function applyDiscount(price, percent) { ... }Python calls these docstrings. JavaScript and Java use JSDoc and Javadoc-style comments. Editors show them on hover and in autocomplete, and tools generate documentation sites.
What to document
- Public functions and classes: what they do, the meaning of each parameter, what’s returned, what can go wrong.
- Non-obvious behavior: units, time zones, side effects, assumptions.
- Modules: a short note at the top on what’s inside and why.
- Examples of use, which often teach faster than prose.
What not to do
- Don’t repeat the code.
"""Adds a and b."""foradd(a, b)is noise. Say something the signature doesn’t. - Don’t let it rot. A wrong docstring is worse than none. Update it when the code changes.
- Don’t document every private helper. Good names (naming) and type annotations (type annotations) carry a lot of the load.