Code Commenting Guidelines
==========================

Alba Core follows a Godot-inspired commenting style: explain the purpose of the
file and class before the reader reaches implementation details.

Module Comments
---------------

Every Python module should start with a docstring that explains:

* what the file owns;
* what input it expects;
* what output it produces;
* what should not be added to the file.

Class Comments
--------------

Every class should explain its role in the architecture. Keep it short, but make
it useful for someone opening the file for the first time.

Function Comments
-----------------

Public methods should have docstrings. Private helpers should have comments or
docstrings when they encode business rules, regex assumptions, scoring choices,
or privacy rules.

Good Comments
-------------

Good comments explain why a rule exists:

.. code-block:: python

   # A property that fails a hard requirement must not be rescued by scoring.

Weak comments just repeat the code:

.. code-block:: python

   # Increment score by 5.

Alba Core prefers the first kind.