code-quality

# Code Quality Skill ## When to Activate Activate this skill when: - Formatting Python code - Running linters - Adding type annotations - Fixing code style issues - Setting up quality tools ## Quick Commands ```bash # Format with Black uv run black . uv run black --check . # Dry run # Lint with Ruff uv run ruff check . uv run ruff check --fix . # Auto-fix # Type check with mypy uv run mypy . # All checks uv run black . && uv run ruff check . && uv run mypy . ``` ## Tool Overview | Tool | Purpose | Speed | Auto-fix | |------|---------|-------|----------| | **Black** | Code formatting | Fast | Yes | | **Ruff** | Linting & imports | Very Fast | Most rules | | **mypy** | Type checking | Moderate | No | ## Installation ```bash uv add --dev black ruff mypy ``` ## Black - Code Formatting Zero-config formatting with consistent style. ```bash uv run black . # Format all uv run black --check . # Dry run uv run black --diff . # Show changes ``` ### Configuration ```toml [tool.black] line-length = 88 target-version = ['py311'] ``` ## Ruff - Fast Linting Rust-based linter replacing flake8, isort, pylint, and 50+ tools. ```bash uv run ruff check . # Check uv run ruff check --fix . # Auto-fix uv run ruff check --show-source . # Show context ``` ### Configuration ```toml [tool.ruff] line-length = 88 target-version = "py311" select = ["E", "W", "F", "I", "B", "SIM"] ignore = ["E501"] # Black handles line length [tool.ruff.per-file-ignores] "__init__.py" = ["F401"] "tests/*" = ["S101"] ``` ### Common Issues - **F401**: Unused import (auto-fixable) - **F841**: Unused variable - **I001**: Import sorting (auto-fixable) - **B008**: Mutable default argument ## mypy - Type Checking Static type checker for Python. ```python def greet(name: str) -> str: return f"Hello, {name}" greet(123) # mypy error: incompatible type "int" ``` ### Configuration ```toml [tool.mypy] python_version = "3.11" warn_return_any = true disallow_untyped_defs = false # Enable gradually check_untyped_defs = true ``` ### Common Type Hints ```python from typing import Optional, List, Dict def find_user(user_id: int) -> Optional[Dict[str, str]]: return database.get(user_id) def process_items(items: List[str]) -> int: return len(items) ``` ## Unified Configuration ```toml # pyproject.toml [tool.black] line-length = 88 target-version = ['py311'] [tool.ruff] line-length = 88 target-version = "py311" select = ["E", "W", "F", "I", "B", "SIM"] [tool.mypy] python_version = "3.11" warn_return_any = true ``` ## Skipping Rules ```python import os # noqa: F401 # Ignore Ruff rule # fmt: off # Disable Black matrix = [[1, 2, 3], [4, 5, 6]] # fmt: on ``` ## Workflow Best Practices ### Development (before commit) ```bash uv run black . && uv run ruff check --fix . && uv run mypy . ``` ### CI/CD (strict, no auto-fix) ```bash uv run black --check . && uv run ruff check . && uv run mypy --strict . ``` ## Gradual Adoption 1. **Start with Black** - Zero config, immediate benefits 2. **Add Ruff** - Basic rules first, expand gradually 3. **Introduce mypy** - Lenient initially, increase strictness ## Code Style Principles ### Clarity Over Cleverness ```python # ❌ Clever but unclear result = [x for x in range(10) if x % 2 == 0 if x > 5] # ✅ Clear and readable even_numbers = [x for x in range(10) if x % 2 == 0] result = [x for x in even_numbers if x > 5] ``` ### Meaningful Names ```python # ❌ Unclear def proc(d, x): return d[x] if x in d else None # ✅ Clear def get_user_by_id(users_dict, user_id): return users_dict.get(user_id) ``` ### Early Returns ```python # ❌ Nested def process(amount, user): if amount > 0: if user.has_payment(): return charge(user, amount) # ✅ Early returns def process(amount, user): if amount <= 0: return "Invalid amount" if not user.has_payment(): return "No payment method" return charge(user, amount) ``` ## Related Resources See `AgentUsage/code_quality.md` and `AgentUsage/code_style_guide.md` for: - IDE integration - Pre-commit hook setup - Comprehensive style guidelines - Error handling patterns