lightsoutAlpha

when-to-document

a doc comment on an export whose name and types already say it, or an inline comment narrating the next line

Agent checkadvisory by defaultbasecode

The argument

When to Document

Default to self-documenting code. Add JSDoc only when:

  • The why is non-obvious — business context, constraints, or gotchas a reader wouldn't guess from the code.
  • The function has a complex contract — non-obvious parameter interactions, intentional error-throwing behavior, usage worth an example.
  • The export is a public API boundary consumed by other packages or external callers.

If the name and types already communicate the purpose, skip the comment.

Inline // comments: default to none. Use only for a non-obvious workaround, a business rule embedded in logic (// 30-day window per billing agreement), or a deliberate deviation and why. Never narrate what the next line does.

The proof

failsrc/billing/getInvoiceLabel.ts
/**
 * Gets the invoice label.
 *
 * @param label - the label
 */
export const getInvoiceLabel = ({ label }: { label: string }): string => {
	// return the label
	return label;
};
passsrc/billing/chargeInvoice.ts
/**
 * Charges an invoice against the payer's default method.
 *
 * The 30-day window is a billing-agreement term, not a technical one — an
 * invoice older than that must be re-issued before it can be charged.
 */
export const chargeInvoice = ({ ageInDays }: { ageInDays: number }): boolean => ageInDays <= 30;

Turn it down

Both lines go in your lightsout.config.json.

"standards-checks": { "when-to-document": "advisory" }
"standards-checks": { "when-to-document": "off" }