bookshelf/docs/contributing.md

Documentation Standards

Philosophy

Prefer self-documenting code and in-code comments over external documentation. Write external docs only when the information cannot live closer to the code.

What belongs where

Content	Where
Why a function does something non-obvious	Inline comment at the relevant line
Contract, parameters, exceptions	Docstring on the function
Module purpose, dependencies, exports	File header comment
Architecture, data flow, system-level decisions	docs/overview.md
Setup, configuration, usage for humans	README.md
Agent/AI session rules	AGENTS.md

Style

• Brief and technical. No preambles, no summaries, no filler.
• No emojis.
• High-level overview only in external docs — implementation details belong in code.
• Present tense, imperative mood for instructions.

Python docstrings

All public functions use Google style: one-line summary, then Args:, Returns:, Raises: sections if non-trivial. List every domain exception the function can raise directly or via propagation.

def crop_save(src: Path, dst: Path, box: tuple[int, int, int, int]) -> None:
    """Crop src image to box and write to dst, overwriting if present.

    Args:
        src: Source image path.
        dst: Destination path; parent directory must exist.
        box: (x, y, w, h) in pixels.

    Raises:
        FileNotFoundError: If src does not exist.
    """

JS file headers

Every JS file starts with a block comment stating: purpose, dependencies (Depends on:), exports (Provides:).

/*
 * helpers.js
 * Pure utility functions with no dependencies on other application modules.
 *
 * Provides: esc(), toast(), isDesktop()
 */

When NOT to document

• Do not add docstrings or comments to code you did not change.
• Do not document implementation details that are already clear from the code.
• Do not keep comments that describe what the code does when the code already says it clearly.
• Do not update docs/overview.md for implementation details — only for structural/architectural changes.