Skip to content

Docstring Style

SilentSwarm uses NumPy-style docstrings for production Python code. The goal is clear API documentation without changing runtime behavior.

Scope

Apply this preset to production modules under src/silent_swarm/ and public operational entry points under exp/scripts/. Tests are excluded unless a test helper becomes a shared public fixture.

Private helpers whose names start with _ only need docstrings when they encode non-obvious behavior, are reused across several public functions, or raise important errors.

Module Header

Every non-empty production module starts with a module docstring in this shape:

"""Short module purpose.

SilentSwarm — Copyright 2026 NexPatch GmbH.
Licensed under the Apache License, Version 2.0. See LICENSE for details.

Optional extra paragraph for architecture, protocol, or runtime notes.
"""

Use this as a Python docstring, not as a comment banner. Do not add copyright or license text unless the repository explicitly adopts that later.

Public Function Template

def public_function(value: int, *, enabled: bool = True) -> str:
    """Do one clear thing.

    Parameters
    ----------
    value : int
        Input value to process.
    enabled : bool, optional
        Whether processing should run.

    Returns
    -------
    str
        Processed result.

    Raises
    ------
    ValueError
        If `value` is outside the supported range.
    """

Omit sections that do not apply. Functions returning None do not need a Returns section when the side effect is obvious from the summary.

Public Class Template

class PublicClass:
    """Coordinate one public responsibility.

    Parameters
    ----------
    name : str
        Human-readable name for this object.

    Attributes
    ----------
    name : str
        Stored display name.

    Notes
    -----
    Add invariants or lifecycle details here when they help users avoid misuse.
    """

For dataclasses and Pydantic models, prefer Attributes for field-level meaning. For Pydantic request/response models, Field(description=...) may be added when it improves API introspection, but only when it does not alter validation behavior.

Review Checklist

  • The docstring describes current behavior, not future intent.
  • Public APIs have enough information to be used from an editor tooltip.
  • Private helpers are not over-documented.
  • No legal header text is introduced accidentally.
  • Examples are short and executable-looking, or omitted.