Code Standards

We optimize for readability over cleverness.

Non-negotiables

• Auto-format on save and in CI. No style debates in PR review.
• Linter passes before merge.
• No commented-out code in main. Delete it; git remembers.
• Dependencies are pinned (lockfile committed).
• Container images are pinned and on the approved list - see conventional/container-images.md.

Conventions

Follow the conventions defined in the conventional/ folder:

• Source structure - see conventional/source-structure.md
• Naming — see conventional/naming.md
• Commit messages — see conventional/commit.md
• HTTP API standard - see conventional/RESTfulAPI.md: MUST/SHOULD rules, each enforced by aioz-common httpapi, the validate:openapi Spectral check or review
• Container images - see conventional/container-images.md
• CI/CD pipeline - see conventional/ci-cd.md
• Releasing - see conventional/release.md
• Security review - see conventional/security.md

Service layout

New to the codebase? conventional/source-structure.md opens with a first-look orientation - the two paths through the code, what to read in your first hour, and where the shared aioz-common library fits.

Every Go backend uses the same shape: one binary, roles as subcommands (api, core, consumer, migrate), and vertical slices under internal/app/. core is where the background jobs run - exactly one instance, holding a flock. aioz-stream and parser-service are the worked references; every other backend moves to it.

Every role drains on SIGTERM rather than cancelling: it stops accepting new work and lets what is in flight finish, so a deploy never throws away a job attempt. Both are in conventional/source-structure.md.

Additional defaults:

• Error handling: return errors with context; don't swallow them. No bare except: / catch (e) {}.
• Logging: structured (JSON), with a request ID. Never log secrets, tokens, or PII.
• Configuration: environment variables, validated at startup. Fail fast on bad config.

SonarQube

Quality Gate must pass before any PR is merged. Treat SonarQube as a non-optional CI check, not a suggestion.

Severity	Required action
Blocker	Fix before merge. No exceptions.
Critical	Fix before merge. No exceptions.
Major	Fix before merge unless demonstrably a false positive.
Minor	Fix if it takes under 5 minutes. Otherwise file a tech-debt ticket and tag the issue.
Info	Use judgment. Not required to fix.

False positives: Mark as Won't Fix or False Positive in SonarQube with a one-line justification. Do not suppress silently via // NOSONAR without a comment explaining why.

Security hotspots: Must be explicitly reviewed and marked Safe or converted to a vulnerability. Leaving them unreviewed blocks the Quality Gate.

New issues only: Fix what you introduce. Pre-existing issues in legacy code are tracked as tech debt through the investment budget (see Tech Debt & Investment), not by blocking current PRs.