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:

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

Weak comments just repeat the code:

# Increment score by 5.

Alba Core prefers the first kind.