Coding Standards

General principles that apply across all languages in this project.

Language-Specific Guidelines

• Python: See PYTHON.md for PEP 8 & PEP 20 conventions
• KQL: See KQL.md for Kusto Query Language conventions

Universal Principles

Structure & Modularity

• Single Responsibility: Each function/module does one thing well
• Small units: Keep functions focused and concise
• Avoid deep nesting: Use early returns, guard clauses
• Extract reusable logic: If you copy-paste, refactor

Comments & Documentation

• Write comments to explain why, not what
• Keep documentation in sync with behavior
• Remove outdated comments promptly

Error Handling

• Use specific error types, not generic catches
• Fail fast with clear error messages
• Log errors with context

Logging

• Use structured logging with consistent fields
• Never log secrets, tokens, or sensitive PII
• Use appropriate log levels

TODOs

• Include owner and context
• Link to tickets when applicable
• Clean up when resolved