coding-standards

amattas 的头像作者 amattas

此代码库的编码风格和结构约定。

📖 中文导读:此代码库的编码风格和结构约定。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: coding-standards description: Coding style and structural conventions for this codebase.

Coding Standards

General Principles

Structure

  • Prefer small, focused functions.
  • Avoid deeply nested conditionals; use early returns.
  • Extract reusable logic into shared modules.

Comments & Documentation

  • Write comments to explain why, not what.
  • Keep docstrings in sync with behavior; avoid outdated comments.

Error & Logging

  • Use structured logging with consistent fields:
    • requestId, userId, component, severity
  • Never log secrets, tokens, or sensitive PII.

Misc

  • Avoid long parameter lists; group related values into objects.
  • Prefer pure functions where practical.
  • Add TODOs with owner and context, e.g.:
    • // TODO [owner]: [short description] ([ticket link])

Language-Specific Standards

For detailed language-specific conventions, see:

  • Python - Includes modularization guidelines (500-800 lines ideal, 1000 max), black/ruff usage, PEP 8, type hints, and testing conventions
  • Swift - iOS/macOS development standards, optionals, protocol-oriented programming, SwiftUI, and memory management
  • Kotlin - Android development standards, coroutines, idiomatic Kotlin, null safety, and Jetpack Compose patterns