aitbc/ai-memory/knowledge/coding-standards.md

Coding Standards

This document defines the coding conventions and quality standards for the AITBC project. All agents should adhere to these when writing or modifying code.

Python Style

• Follow PEP 8 with 4-space indentation.
• Maximum line length: 88 characters (Black default) or 100 if team agrees.
• Use type hints for function signatures and public methods.
• Use snake_case for variables and functions; PascalCase for classes; UPPER_SNAKE_CASE for constants.

Formatting

• Black code formatter is preferred (if configured). Otherwise, consistent indentation and spacing.
• Use isort to sort imports: standard library, third-party, local.
• Remove unused imports and variables.

Imports

Prefer absolute imports over relative imports for clarity. For intra-package modules, absolute imports from the package root are fine.

Example:

from app.services.trading_surveillance import SurveillanceService
# not
from ..services.trading_surveillance import SurveillanceService

However, within the cli commands, we currently add sys.path to include apps/coordinator-api/src and then import via app.services.xxx. This is acceptable for now, but consider packaging coordinator-api as a dependency in the future.

Docstrings

Public functions, classes, and modules should have docstrings in Google style or NumPy style. Example (Google):

def send_transaction(sender: str, recipient: str, amount: int) -> str:
    """Send coins from sender to recipient.

    Args:
        sender: Wallet address of sender.
        recipient: Wallet address of recipient.
        amount: Amount in smallest unit (e.g., wei).

    Returns:
        Transaction hash.

    Raises:
        InsufficientBalanceError: If sender lacks funds.
    """

Error Handling

• Use specific exception types; avoid bare except:. Prefer except SomeError:.
• Log exceptions with context; do not swallow silently.
• For CLI commands, exit with non-zero status on error; print useful message to stderr.

Logging

• Use the logging module, not print() for informational output.
• Configure log level via environment variable LOG_LEVEL.
• Use module-level logger: logger = logging.getLogger(__name__).
• Log at appropriate levels: debug for verbose, info for normal operations, warning for recoverable issues, error for failures.

Async Code

• Use async def for I/O-bound functions; await appropriately.
• Avoid blocking calls (like time.sleep) in async functions; use asyncio.sleep.
• Use asyncio.create_task for fire-and-forget; handle exceptions.

Testing

• Write unit tests for new features and bug fixes.
• Place tests in tests/ directory adjacent to package or in tests/ at repo root.
• Use pytest fixtures for common setup/teardown.
• Aim for high coverage of critical paths; not necessarily 100% trivial code.
• Tests should be hermetic: no external service dependencies (use mocking) except integration tests (marked separately).

Commit Messages

• Follow Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:.
• Keep subject line under 50 characters; body wrapped at 72 if needed.
• Reference issue numbers: Closes #12 or Fixes #34.

Git Workflow

• Create feature branches from main: aitbc1/<issue>-<slug>.
• Commit logical units; avoid mixing unrelated changes.
• Push frequently to remote to back up work.
• Before opening PR, ensure tests pass locally; run pre-commit if configured.
• Request review from @aitbc (or appropriate agent).

Security

• Never commit secrets (tokens, private keys) to the repository. Use environment variables or config files outside version control.
• Validate external input (user-provided data) to prevent injection attacks.
• Use parameterized queries for SQL; never string-concatenate.

Performance

• Avoid N+1 queries; use eager loading where appropriate.
• Profile slow code; add indexes to database if needed.
• Consider async for I/O-bound services.

API Design

• RESTful endpoints: use nouns, plural (/v1/jobs, /v1/wallets), proper HTTP verbs.
• Version APIs (/v1/) to allow future upgrades.
• Use appropriate status codes (200, 201, 400, 404, 409, 500).
• Return JSON with consistent structure: {"data": ..., "error": null} or error envelope.

Documentation

• Update README.md when user-facing changes occur.
• Document new CLI commands in README.md or docs/.
• Keep ai-memory/knowledge/ files up to date with environment details, dependencies, and coding standards.

Code Review

• Respect Stability Rings: Ring 0 (core packages) requires meticulous review.
• Reviewers: look for correctness, security, performance, readability, tests.
• Approve only when CI passes and code meets standards.
• Address review comments promptly.

---

By adhering to these standards, we maintain a clean, maintainable, and robust codebase.