/couchbase-coding-standards

name: couchbase-coding-standards
description: "Apply coding standards and a style guide for writing production application code against Couchbase, combining general software-engineering best practices (naming, functions, error handling, testing, docstrings, version control, code review, secrets hygiene) with Couchbase-specific conventions (SDK idioms, document-key naming, exception and retry handling, durability, parameterized SQL++, connection lifecycle). Use whenever the user asks about coding standards, code style, a style guide, clean code, naming conventions, structuring Couchbase application code, idiomatic SDK usage, how to write or review Couchbase code, code-review checklists, linting, formatting, testing Couchbase code, or best practices for writing Couchbase apps. Distinct from couchbase-app-integration (SDK mechanics: pooling, durability, scan consistency) and couchbase-data-modeling (document design) — this is the how-to-write-and-review-the-code layer on top of them. Use proactively when reviewing or authoring code that touches Couchbase."
license: MIT

Couchbase coding standards & style guide

A skill for *writing and reviewing* clean, correct, maintainable application code against Couchbase. It combines general software-engineering discipline with the Couchbase-specific conventions that keep application code idiomatic, safe, and resilient.

Distinct from:

• `couchbase-app-integration` — SDK *mechanics* (connection pooling, durability levels, scan consistency, retry primitives). This skill assumes those mechanics and covers how to *write the code* around them well.
• `couchbase-data-modeling` — *what shape* the documents take. This skill covers *how the code that reads and writes them* is structured and named.
• `couchbase-sqlpp-tuning` — query *performance*. This skill covers query *safety in code* (parameterization, injection, result handling).

If the conversation is "how should this Couchbase code be written / named / structured / reviewed," this is the right skill.

When this skill applies

• "What are the coding standards / style guide for Couchbase apps?"
• "Review this Couchbase code."
• "How should I name my document keys / SDK objects / functions?"
• "Is this idiomatic use of the SDK?"
• "How do I handle Couchbase errors properly in code?"
• "How do I write testable code against Couchbase?"
• "How do I avoid SQL++ injection?"
• "Set up linting / formatting / a review checklist for a Couchbase project."

Pick the right reference

| Question | Read | |---|---| | "General clean-code standards — naming, functions, comments, tests, version control, reviews, secrets" | `references/general-coding-standards.md` | | "Idiomatic SDK use — connection lifecycle, KV vs query, batching, async, per-language idioms" | `references/couchbase-sdk-idioms.md` | | "Document key + field naming conventions, type discriminators, metadata fields" | `references/key-and-document-conventions.md` | | "Couchbase exceptions, retry/backoff, idempotency, durability in code, transactions hygiene" | `references/error-handling-and-resilience.md` | | "Writing SQL++ in application code safely — parameterization, injection, scan consistency, pagination" | `references/sqlpp-in-code.md` |

Core principles

**Principle 1 — Idiomatic beats clever.** Each SDK has a grain: Python uses context managers and type hints, Java uses reactive streams / `CompletableFuture`, Node uses promises/async-await, Go uses explicit error returns. Code that fights the SDK's idioms is harder to read, review, and maintain. Follow the grain of the language and the SDK, not a house dialect imposed across all of them.

**Principle 2 — Correctness at the boundary is a coding standard, not an afterthought.** Couchbase code fails in specific, recurring ways: transient errors, timeouts, ambiguous durability, missing documents, CAS mismatches, injection through string-built SQL++. Handling these is not "extra hardening" bolted on later — it is part of writing the code correctly the first time. Every read can miss; every write can be ambiguous; every query built from user input is an injection risk until parameterized.

**Principle 3 — Optimize for the reader and the reviewer.** Code is read far more than written. Names carry intent, functions do one thing, keys are self-describing, and the non-obvious "why" is commented (never the obvious "what"). A reviewer should be able to tell *what* a document key refers to, *whether* an error path is handled, and *why* a durability level was chosen — from the code alone.

**Principle 4 — Verify version-sensitive symbols; never assert an SDK API from memory.** SDK method names, option objects, and exception types differ across major SDK versions and drift over time. Pin every version-sensitive symbol against the project's actual SDK version (check existing usage in the codebase first, then the versioned SDK docs). If a symbol can't be verified against the pinned version, flag the line rather than guessing. This applies to review feedback as much as to authored code.

Using this skill to review code

When reviewing, walk these in order and cite the specific reference for any issue found:

1. **Correctness** — reads that can miss, writes with unhandled ambiguity, unparameterized SQL++, CAS/idempotency gaps → `error-handling-and-resilience.md`, `sqlpp-in-code.md` 2. **Idiom** — fighting the SDK grain, connections opened per-operation, blocking calls in async paths → `couchbase-sdk-idioms.md` 3. **Naming & shape** — opaque keys, missing type discriminators, inconsistent field naming → `key-and-document-conventions.md` 4. **General hygiene** — function size, naming, comments, tests, secrets in code → `general-coding-standards.md`

Report findings direct over diplomatic: state the issue, cite the standard, show the fix. Flag opinions as opinions, separate from correctness defects.

Related skills

• `couchbase-app-integration` — the SDK mechanics this skill's idioms sit on top of