solpbc.org / solstone
personal memory agent
fork atom
solstone / talent / coding / reference / coding-standards.md
at main 2.8 kB view raw view code
Jer Miller refactor: rename muse → talent project-wide
cb19a905

Coding Standards#

Language & Tools#

  • Ruff (make format) - Formatting, linting, and import sorting
  • mypy (make check) - Type checking
  • Configuration in pyproject.toml

Naming Conventions#

  • Modules/Functions/Variables: snake_case
  • Classes: PascalCase
  • Constants: UPPER_SNAKE_CASE
  • Private Members: _leading_underscore

Code Organization#

  • Imports: Prefer absolute imports, grouped (stdlib, third-party, local), one per line
  • Docstrings: Google or NumPy style with parameter/return descriptions
  • Type Hints: Should be included on function signatures (legacy helpers may still need updates)
  • File Structure: Constants → helpers → classes → main/CLI

File Headers#

All source code files (but not text or markdown files or prompts) must begin with a license and copyright header:

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 sol pbc

Use // comments for JavaScript files.

Development Principles#

  • DRY, KISS, YAGNI: Extract common logic, prefer simple solutions, don't over-engineer
  • Single Responsibility: Functions/classes do one thing well
  • Conciseness & Maintainability: Clear code over clever code
  • Robustness: Minimize assumptions that must be kept in sync across the codebase, avoid fragility and increasing maintenance burden.
  • Self-Contained Codebase: All code that depends on this project lives within this repository—never add backwards-compatibility shims, fallback aliases, re-exports for moved symbols, deprecated parameter handling, or legacy support code. When renaming or removing something, update all usages directly. For journal data format changes, write a migration script (see docs/APPS.md for maint commands) instead of adding compatibility layers.
  • Trust system path resolution: Never set _SOLSTONE_JOURNAL_OVERRIDE or bypass get_journal() from application code, agent prompts, subprocess environments, or service files. The env var exists only for tests and Makefile sandboxes. See reference/environment.md.
  • Security: Never expose secrets, validate/sanitize all inputs
  • Performance: Profile before optimizing
  • Git: Small focused commits, descriptive branch names. Run git commands directly (not git -C) since you're already in the repo.

Dependencies#

  • Minimize Dependencies: Use standard library when possible
  • All Dependencies: Add to dependencies in pyproject.toml
  • Package Manager: uv — lock file (uv.lock) is committed, make install syncs from it
  • Installation: make install (creates isolated .venv/, syncs deps from lock file, symlinks sol to ~/.local/bin)
  • Updating: make update upgrades all deps to latest and regenerates the lock file