Skip to content

CODESTYLE.md

Latest commit

 

History

History
83 lines (55 loc) · 3.83 KB

CODESTYLE.md

File metadata and controls

83 lines (55 loc) · 3.83 KB
Raw

Code Style

Use this document as the durable source of truth for source formatting, naming, documentation style, and commenting standards in Monitor.

Scope

These rules apply to runtime scripts, tests, helper scripts, and code-bearing configuration files that support comments. Markdown documents use their headings and opening prose as their file-level explanation.

Monitor is currently a Bash-first prototype. If the project later adopts another runtime, update this file, README.md, and AGENTS.md in the same change.

General Source Style

  • Keep runtime code in src/ and mirror tests in tests/.
  • Prefer Bash for the first CLI. Use Python only for focused standard-library helpers when Bash would make JSON, path, or text processing fragile.
  • Use 2 spaces for Markdown, YAML, JSON, TOML, and similar structured files. Use the dominant ecosystem style for future languages.
  • Use snake_case for Bash function names and variables.
  • Use uppercase names only for exported environment variables such as MONITOR_INTERVAL_SECONDS.
  • Use kebab-case for ordinary Markdown filenames outside root control documents.
  • Name ExecPlans under plans/ with the ordered NN-kebab-case-name.md pattern described in PLANS.md.
  • Keep root control documents in uppercase names such as README.md, PRODUCT.md, and ARCHITECTURE.md.

Bash Rules

Shell scripts must start with:

#!/usr/bin/env bash

Use strict mode for runtime and test scripts unless a specific command requires narrower handling:

set -euo pipefail

Quote variable expansions unless intentional word splitting is required. Prefer arrays for command arguments. Avoid eval.

Validate required external commands before doing work. For Monitor v1 that means checking bash, date, mkdir, mktemp, sleep, powershell.exe, wslpath, codex, and scripts/win-screenshot as applicable.

Handle paths with spaces. Use mkdir -p before writing nested output paths.

Do not print secrets. Monitor v1 should not need OpenAI API keys, but the same rule applies to any future token-like setting.

Commenting Standard

Comments should help a technically competent reader understand purpose, assumptions, side effects, and failure behavior. Avoid comments that restate syntax.

Every source file that supports comments must start with a header comment explaining:

  • what the file does
  • the main functions or entry points it owns
  • how it fits into Monitor
  • important external commands, filesystem writes, or privacy assumptions

Every non-trivial Bash function must have a short comment immediately above it. The comment should explain what the function expects, what it writes or returns, and which failures callers should expect.

Inside multi-step functions, add short comments before meaningful phases such as loading config, validating commands, capturing screenshots, invoking Codex, writing summaries, or handling failures.

Documentation Style

Keep documentation in the file that owns the relevant truth:

  • PRODUCT.md describes current capabilities, workflows, constraints, and user-visible limits.
  • ROADMAP.md describes durable future direction and non-priorities.
  • DESIGN.md describes terminal UX and future interface language.
  • ARCHITECTURE.md describes structure, ownership, boundaries, and invariants.
  • README.md describes setup, commands, dependencies, and contributor onboarding.
  • PLANS.md describes how ExecPlans must be written and maintained.
  • AGENTS.md describes repository-specific instructions for coding agents.

Do not leave generic template placeholders in root control documents. If a decision is deferred, name the specific open question.

Validation Expectations

Run:

bash -n scripts/win-screenshot src/monitor.sh tests/monitor_cli_test.sh
tests/monitor_cli_test.sh
rg --files --hidden -g '!.git/**'
git diff --check
git status --short