Skip to content

code-style.md

Latest commit

 

History

History
235 lines (165 loc) · 3.53 KB

code-style.md

File metadata and controls

235 lines (165 loc) · 3.53 KB

Code Style Guide

Coding standards and style guidelines for FARP.

Formatting

Black

Use Black for code formatting:

black src/ dashboard/ tests/

Configuration (pyproject.toml):

[tool.black]
line-length = 100
target-version = ['py311']

isort

Use isort for import ordering:

isort src/ dashboard/ tests/

Configuration:

[tool.isort]
profile = "black"
line_length = 100

Type Hints

Use type hints for all functions:

from decimal import Decimal
from typing import Optional, List, Dict

def calculate_pnl(
    quantity: Decimal,
    cost: Decimal,
    current_price: Decimal
) -> Decimal:
    """Calculate profit/loss."""
    return (current_price - cost) * quantity


def get_positions(
    as_of_date: Optional[date] = None
) -> List[Dict[str, Any]]:
    """Get all positions."""
    pass

Type Checking

mypy src/

Docstrings

Use Google-style docstrings:

def calculate_var(
    returns: np.ndarray,
    confidence: int = 95
) -> float:
    """
    Calculate Value at Risk.
    
    Args:
        returns: Array of historical returns.
        confidence: Confidence level (95 or 99).
    
    Returns:
        VaR as a decimal (e.g., 0.02 for 2%).
    
    Raises:
        ValueError: If confidence level is invalid.
    
    Example:
        >>> var = calculate_var(returns, confidence=99)
        >>> print(f"VaR: {var:.2%}")
    """
    pass

Naming Conventions

Type Convention Example
Classes PascalCase PositionCalculator
Functions snake_case calculate_pnl
Variables snake_case total_value
Constants UPPER_SNAKE DEFAULT_CURRENCY
Private _prefix _cache, _validate

File Organization

"""
Module docstring explaining purpose.
"""

# Standard library imports
from datetime import date
from decimal import Decimal
from typing import Optional, List

# Third-party imports
import numpy as np
from sqlalchemy import select

# Local imports
from src.config import settings
from src.database.models import Trade

# Constants
DEFAULT_LOOKBACK = 252

# Module-level logger
logger = get_logger(__name__)


# Classes
class Calculator:
    """Calculator class."""
    pass


# Functions
def helper_function():
    """Helper function."""
    pass

Error Handling

# Use specific exceptions
class FARPError(Exception):
    """Base exception for FARP."""
    pass

class ValidationError(FARPError):
    """Data validation error."""
    pass

# Log errors with context
try:
    result = calculate()
except ValueError as e:
    logger.error("Calculation failed", error=str(e), symbol=symbol)
    raise ValidationError(f"Invalid data: {e}")

Logging

Use structured logging:

from src.utils.logging import get_logger

logger = get_logger(__name__)

# Good - structured
logger.info("Trade processed", trade_id=42, symbol="AAPL", side="BUY")

# Avoid - unstructured
logger.info(f"Processed trade {trade_id} for {symbol}")

SQL Queries

Use SQLAlchemy ORM when possible:

# Good - ORM
positions = db.query(Position).filter(
    Position.as_of_date == today
).all()

# Acceptable - when needed
from sqlalchemy import text
result = db.execute(text("SELECT * FROM positions WHERE ..."))

Pre-commit Checks

# Format
black src/ dashboard/
isort src/ dashboard/

# Type check
mypy src/

# Test
pytest tests/ -v

Related