How to write JSDoc and docstrings that developers actually read
JSDoc syntax, Python docstrings, parameter documentation, return types, example documentation, when to skip docstrings
Writing API Documentation That Serves Developers
Public APIs — functions used by other developers or other modules — deserve documentation. Internal private helpers usually don't. The key rule: document the public interface, not the implementation.
Good JSDoc explains what the function does (not how), what each parameter expects (type and meaning), and what the return value represents:
/**
* Calculates the total price of an order after applying discounts.
* Does not include taxes — call applyTax() separately.
*
* @param {Object} order - The order object from the database
* @param {number} order.subtotal - Subtotal in cents
* @param {string} discountCode - Validated promo code or empty string
* @returns {number} Final price in cents after discount, minimum 0
*/
function calculateOrderTotal(order, discountCode) { }Python docstrings follow Google or NumPy style — pick one and use it consistently:
def calculate_order_total(order: dict, discount_code: str) -> int:
"""Calculate total price after discounts, excluding tax.
Args:
order: Order dict with subtotal in cents.
discount_code: Validated promo code or empty string.
Returns:
Final price in cents, minimum 0.
Raises:
ValueError: If subtotal is negative.
"""When to skip docstrings: private helper functions, trivial getters, functions whose name and parameters are already completely self-explanatory.
Document edge cases and gotchas that a caller would never discover until they hit a bug: minimum values, what happens with empty inputs, what side effects to expect. These are the comments developers actually bookmark and return to.