126 lines
4.8 KiB
Markdown
126 lines
4.8 KiB
Markdown
# 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:
|
|
```python
|
|
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):
|
|
```python
|
|
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. |