code-style-and-zen-of-python

Code Style and Zen of Python

Line Length

• Max 88 chars (per Ruff config)

Comments

File-Level Comments

Be THOROUGH at the top of files. Explain what the file does, why it exists, and how it fits into the larger system. This helps both humans and AI understand context quickly.

"""User authentication and session management.

Handles user login, logout, token generation, and session validation.
Integrates with external OAuth providers (Google, GitHub) and maintains
local session state in Redis for performance. Session tokens expire after
24 hours but can be refreshed up to 7 days from initial login.
"""

Function Comments

Keep function docstrings USEFUL without redundant fluff. Type hints already document parameters and return types, so focus the docstring on what the function does and why.

# Standard pattern for complex functions - explain the what and why
def create_agent_from_task(self, task_id: str) -> dict:
    """Create a new agent from a ClickUp task description.

    Parses task description for agent requirements, generates the .agent
    file with system/user prompts, creates PR with the new file, and
    returns PR URL for review.
    """

# Simple functions need just one clear line
def validate_email(email: str) -> bool:
    """Check if email format is valid and domain is not blacklisted."""

def process_payment(order_id: str, amount: Decimal) -> Payment:
    """Charge the customer via Stripe and update order status to paid."""

def send_welcome_email(user: User) -> None:
    """Send onboarding email with account setup instructions."""

def calculate_shipping_cost(weight: Decimal, destination: str) -> Decimal:
    """Calculate shipping based on weight and zone rates from ShipStation."""

Avoid restating type hints in Args/Returns sections - they add no value since types are already declared.

Inline Comments

Be SPARSE with inline comments. Only add them when the code is doing something non-obvious or when explaining business logic that isn't clear from the code itself.