code-quality-rules

Code Quality Rules — Aiyu Agent Kit

Standards for maintainable, readable, and testable code.

---

🔴 CRITICAL: Code Fundamentals

Naming Conventions

# ✅ GOOD — Clear, descriptive names
def calculate_user_total_spending(user_id: int) -> float:
    user_orders = get_orders_by_user(user_id)
    return sum(order.amount for order in user_orders)

# ❌ BAD — Abbreviations, unclear intent
def calc(u_id):
    o = get_o(u_id)
    return sum(x.a for x in o)

Naming standards:

• Functions/Methods: verb_noun format (get_user, validate_input)
• Classes: Noun in PascalCase (UserManager, PaymentGateway)
• Constants: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
• Booleans: Prefix with is_, has_, can_ (is_active, has_permission)

Function Design

# ✅ GOOD — Single responsibility, clear purpose
def validate_email(email: str) -> bool:
    """Check if email format is valid."""
    return re.match(r'^[\w\.-]+@[\w\.-]+\.\w+$', email) is not None

def send_welcome_email(user: User) -> None:
    """Send welcome email to new user."""
    # Implementation

# ❌ BAD — Multiple responsibilities
def process_user(user_data):
    validate_email(user_data['email'])
    save_to_database(user_data)
    send_welcome_email(user_data)
    update_analytics(user_data)

Function limits:

• Max 20 lines per function
• Max 3 parameters (use objects for more)
• Do one thing, do it well

---

🟡 HIGH: Maintainable Code

Comments & Documentation

# ✅ GOOD — Explain WHY, not WHAT
def calculate_discount(price: float, user: User) -> float:
    """
    Apply discount based on user tier.
    
    Premium users get 20% off as per business rule #123.
    Regular users get 10% off during promotional periods.
    """
    if user.is_premium:
        return price * 0.8  # 20% discount for premium
    return price * 0.9  # 10% standard discount

# ❌ BAD — Redundant comments
def add(a, b):
    # Add a and b together
    return a + b

Error Handling