name: commenting-c-and-python description: "Follow bocpy commenting and documentation conventions. Use when: adding comments to C or Python files, writing docstrings, documenting structs or classes, adding Doxygen doc-comments, using Sphinx param style, suppressing linter warnings with noqa, or following flake8 style rules (Q000, D205, D209, N802)."

Commenting C and Python Files

This skill describes the commenting conventions used across the bocpy project. Follow these patterns when adding or editing comments so the codebase stays consistent.

C Files (_core.c, _math.c)

Function-Level Documentation — Doxygen /// Style

Every non-trivial function gets a Doxygen doc-comment block immediately above its signature. Use triple-slash /// lines with @ tags in this order:

1. @brief — one-line summary (sentence case, no trailing period)
2. @details — optional longer explanation
3. @note — optional caveats or side-effects
4. @param — one per parameter (description starts uppercase)
5. @return — what the function returns

/// @brief Creates a new BOCTag object from a Python Unicode string
/// @details The result object will not be dependent on the argument in any way
/// (i.e., it can be safely deallocated).
/// @param unicode A PyUnicode object
/// @param queue The queue to associate with this tag
/// @return a new BOCTag object
BOCTag *tag_from_PyUnicode(PyObject *unicode, BOCQueue *queue) {

For short helper functions, @brief alone is enough:

/// @brief Convenience method to obtain the interpreter ID
/// @return the ID of the currently running interpreter
static inline PY_INT64_T get_interpid() {

Struct Field Documentation

Document struct fields with /// @brief (and optionally /// @details) on the line(s) above the field:

typedef struct boc_message {
  /// @brief The tag associated with this message.
  /// @details This will be used by processes calling receive() and will create
  /// an affinity with a queue.
  struct boc_tag *tag;
  /// @brief whether the contents of this message were pickled
  bool pickled;
  /// @brief the threadsafe cross-interpreter data (the contents of the message)
  XIDATA_T *xidata;
} BOCMessage;

Inline Comments — // Style

Use // for short explanatory comments inside function bodies. Place them on the line above the code they describe, at the current indentation level:

  // two possibilities:
  // 1. queue is empty
  // 2. queue is inconsistent

  // step 1: swap the new node in as the new head
  node->next = head;

End-of-line // comments are reserved for preprocessor version annotations:

#if PY_VERSION_HEX >= 0x030E0000 // 3.14

/* */ Block Comments — Sentinel Only

Traditional block comments are used exclusively as sentinel markers in PyMethodDef and slot arrays:

    {NULL} /* Sentinel */

Do not use /* */ for any other purpose.

Method Table Doc Strings

Short one-phrase descriptions in PyMethodDef tables:

static PyMethodDef CownCapsule_methods[] = {
    {"get", CownCapsule_get, METH_NOARGS, "internal"},
    {"set", CownCapsule_set, METH_VARARGS, "internal"},
    {"bid", BehaviorCapsule_bid, METH_NOARGS, "Gets the ID for the behavior"},
};

Module Doc String

Set .m_doc in the PyModuleDef to a short description:

    .m_doc = "Provides the underlying C implementation for the core BOC "
             "functionality",

TODO Comments

Use // TODO on its own line, followed by the item(s):

// TODO
// invert 2x2, 3x3, general algorithm for NxN
// det
// trace

Python Files

Module-Level Docstring

Every .py file starts with a single-line triple-quoted docstring. Sentence case, ends with a period.

"""Behavior-oriented Concurrency."""

"""AST transformers that export when-decorated functions as behaviors."""

Class Docstrings

Use a triple-quoted docstring immediately after the class statement. For simple classes, a single-line docstring is preferred. For complex classes, use a summary line, a blank line, then a longer description. Sentence case, ends with a period.

class Cown(Generic[T]):
    """Lightweight wrapper around the underlying cown capsule."""

class BOCModuleTransformer(ast.NodeTransformer):
    """Prepares a main module for transpiling.

    This transformer collects the names of classes, functions, imports,
    and filters out everything else at the root level.
    """

Function / Method Docstrings

Start with a verb in imperative mood. Single-line for simple functions, multi-line for complex ones. Ends with a period.

Single-line:

def acquire(self):
    """Acquires the cown (required for reading and writing)."""

Multi-line (summary + body):

def release(self):
    """Release the cown to the next behavior.

    This is called when the associated behavior has completed, and thus can
    allow any waiting behavior to run.

    If there is no next behavior, then the cown's `last` pointer is set to null.
    """

Parameter Documentation — Sphinx Style

Use Sphinx :param: / :type: / :return: / :rtype: fields for parameter documentation. This is the single accepted style across the project.

def export_module(tree: ast.Module, path: str = None) -> ExportResult:
    """Extract an AST as a BOC-enlightened module with generated behaviors.

    :param tree: The source tree
    :type tree: ast.Module
    :return: An export result with code and metadata
    :rtype: ExportResult
    """

def __init__(self, num_workers: Optional[int], export_dir: Optional[str]):
    """Creates a new Behaviors scheduler.

    :param num_workers: The number of worker interpreters to start.  If
        None, defaults to the number of available cores minus one.
    :type num_workers: Optional[int]
    :param export_dir: The directory to which the target module will be
        exported for worker import.  If None, a temporary directory will
        be created and removed on shutdown.
    :type export_dir: Optional[str]
    """

.pyi Stub File Docstrings

The stub file __init__.pyi uses Sphinx-style docstrings on every public function, class, and constant. Constants use an attribute docstring on the line after the declaration:

TIMEOUT: str
"""Sentinel value returned by :func:`receive` when a timeout occurs."""

def send(tag: str, contents: Any):
    """Sends a message.

    :param tag: The tag is an arbitrary label that can be used to receive this message.
    :type tag: str
    :param contents: The contents of the message.
    :type contents: Any
    """

Inline # Comments

Use # comments for short notes inside function bodies. Place them on the line above the code, at the current indentation:

        orphan_cowns = _core.cowns()
        if len(orphan_cowns) != 0:
            logger.debug("acquiring orphan cowns")
            # at this stage all behaviors have exited, but it may be the case
            # that some cowns are released but associated with this interpreter.
            # by acquiring them, we ensure that the XIData objects have been
            # freed _before_ this interpreter is destroyed.

Same-line # comments are acceptable for very short annotations:

        except RuntimeError:
            pass  # already destroyed

# noqa: Suppression Comments

Suppress linter warnings with # noqa: CODE at the end of the line. Place the suppression on the line that contains the violation, not a surrounding line:

    def visit_FunctionDef(self, node: ast.FunctionDef):  # noqa: N802

# CORRECT — noqa on the line that references the loop variable
@when(acc)
def _(a):
    a.value.add(val_to_add)  # noqa: B023

# WRONG — noqa on the def line does not suppress the reference on the next line
@when(acc)
def _(a):  # noqa: B023
    a.value.add(val_to_add)   # ← still triggers B023

# BEGIN / # END Markers

Code-generation insertion points in worker.py:

# BEGIN boc_export
# END boc_export

Linting Rules (flake8)

The project enforces style with flake8 (config in .flake8):

Multi-line Class Docstrings (D205 / D209)

A multi-line docstring must have a summary line, a blank line, then the body. The closing """ must be on its own line:

# CORRECT
class Foo:
    """Short summary line.

    Longer description goes here after the blank line.
    """

# WRONG — triggers D205 and D209
class Foo:
    """This wraps onto a second line
    without a blank separator."""

Naming in Test Files (N802)

Test function names must be lowercase. Even when testing a property like .T, spell the test name with a lowercase letter:

# CORRECT
def test_t_equals_transpose(self, mat): ...

# WRONG — triggers N802
def test_T_equals_transpose(self, mat): ...

Quick Reference

Common Pitfalls