Home Standards

Coding Standards

Guidelines for writing clean, maintainable code and collaborating effectively as a team.

Code Style

Consistent code style makes our codebase easier to read and maintain. Follow these guidelines for all code contributions.

Py Python Guidelines

Follow PEP 8

Use 4 spaces for indentation, limit lines to 88 characters (Black formatter default).

Use type hints

Add type annotations to function parameters and return values.

def calculate_total(items: list[dict], tax_rate: float) -> float:
    """Calculate total price with tax."""
    subtotal = sum(item["price"] for item in items)
    return subtotal * (1 + tax_rate)

Use loguru for logging

Always use the loguru module for logging. Keep log messages concise and informative.

from loguru import logger

logger.info("Processing started")
logger.error(f"Failed to process item: {item_id}")

Use meaningful names

Variables and functions should clearly describe their purpose.

Good

user_count = len(active_users)

Avoid

x = len(u)

JS JavaScript / TypeScript Guidelines

Use const and let

Prefer const for values that won't be reassigned. Never use var.

Use arrow functions

Prefer arrow functions for callbacks and anonymous functions.

const doubled = numbers.map(n => n * 2);

Use async/await

Prefer async/await over .then() chains for better readability.

General Best Practices

KISS + YAGNI + DRY

Keep It Simple, You Aren't Gonna Need It, Don't Repeat Yourself. Write only what's needed, avoid premature optimization.

Write self-documenting code

Code should be readable without excessive comments. Use comments to explain "why", not "what".

Handle errors gracefully

Always handle potential errors. Log errors with enough context to debug issues.

Git Workflow

We use a feature branch workflow. All changes go through pull requests before merging to main.

Branch Naming

Use descriptive branch names with a prefix indicating the type of change:

feature/

New features or enhancements

Example: feature/user-authentication

bugfix/

Bug fixes

Example: bugfix/login-redirect

hotfix/

Urgent production fixes

Example: hotfix/security-patch

docs/

Documentation updates

Example: docs/api-readme

Commit Messages

Write clear, concise commit messages that describe what changed and why.

Good Examples

Add user authentication endpoint
Fix null pointer exception in data parser
Update dependencies to patch security vulnerability
Refactor database connection pooling for better performance

Avoid

Fixed stuff
WIP
asdfasdf
Updated code

Typical Workflow

1

Update your local main branch

git checkout main && git pull origin main

2

Create a feature branch

git checkout -b feature/your-feature-name

3

Make changes and commit frequently

git add . && git commit -m "Your descriptive message"

4

Push and create a Pull Request

git push origin feature/your-feature-name

Pull Requests

All code changes must go through a Pull Request (PR) and be reviewed before merging.

PR Requirements

Descriptive title - Summarize the change in the PR title
Clear description - Explain what changed and why in the PR body
Small, focused changes - PRs should address one concern at a time
Request review - Tag a team member to review your code
Address feedback - Respond to review comments and make requested changes

Code Review Guidelines

When reviewing code, focus on:

Correctness

Does the code do what it's supposed to do?

Readability

Is the code easy to understand?

Maintainability

Will this code be easy to modify in the future?

Security

Are there any security concerns? (CSRF tokens, input validation, etc.)

Documentation

Good documentation helps the team understand and maintain code. Here's what to document and how.

What to Document

README files - Every repo should have a README with setup instructions
API documentation - Document endpoints, parameters, and responses
Complex logic - Add comments explaining non-obvious algorithms
Configuration - Document environment variables and config options

Python Docstrings

Use docstrings for functions and classes:

def process_order(order_id: str, user_id: int) -> dict:
    """
    Process an order and return the result.

    Args:
        order_id: The unique identifier for the order.
        user_id: The ID of the user placing the order.

    Returns:
        A dictionary containing the processed order details.

    Raises:
        ValueError: If the order_id is invalid.
    """
    # Implementation here
    pass

Quick Reference

Remember

• Include CSRF tokens where necessary
• Use loguru for logging
• Keep code simple (KISS)
• Don't over-engineer (YAGNI)
• Avoid repetition (DRY)

Before Committing

• Test your changes locally
• Review your own diff
• Write a clear commit message
• Check for console errors

Need Help?

• Ask in team chat
• Check existing code for patterns
• Review the Team page
• Pair program with a teammate