General Rules

Base Coding Rules

SPPAS follows the PEP8 style guide. Only the specific rules below override the base ones.

Commit Messages

Each commit message must follow the structure name.of.module: Action message, where "Action" includes but is not limited to "added", "fixed", "cleaned", "removed". Example: sppas.src.annotations.cuedspeech.model: Fixed test for model 4 -- custom rules. A long description is welcome explaining the reason(s) of these changes but not the changes themselves.

Naming

• Classes: PascalCase or sppas-prefixed CamelCase.
• Functions, variables: snake_case.
• Constants: UPPER_SNAKE_CASE.
• One class per file; file name in snake_case.

Formatting

• Use 4 spaces for indentation.
• No special characters like page breaks.

Commenting

Comments are in American English, written as full sentences explaining what is not obvious. Rewrite unclear code instead of over-commenting.

Python Language

• Follow PEP257 and PEP484 with SPPAS-specific adjustments.
• Max line length: 119 characters.
• No inline comments, no @property decorator, no typing library.
• Always use explicit comparisons (if greeting == 0:).

Docstrings

Short summary ≤79 chars. Markdown syntax limited to markdown2. Example:

def add(a: int, b: int) -> int:
     """Return the sum of two integers.
 
     :param a: (int) First value
     :param b: (int) Second value
     :return: (int) The sum
     """

Accessibility Justification

Rules are adapted to improve readability for visually impaired developers: no typing library, explicit comparisons, 119-char lines, clear logical flow.

JavaScript Language

• Object-oriented design with ES6 modules.
• 2-space indentation, single quotes, semicolons required.
• Classes: PascalCase. Functions/variables: camelCase. Constants: UPPER_SNAKE_CASE.
• Max line length: 119 characters.
• Explicit comparisons; avoid truthy/falsy ambiguity.

Comments and Documentation

Use JSDoc syntax. Write concise comments in American English explaining the “why”.

/**
  * Fetch data from a given API endpoint.
  *
  * @param {string} url - The API endpoint to fetch data from.
  * @returns {Promise<Object>} The JSON response data.
  */
 async function fetchData(url) { ... }