Docs Code Style

Code Style

Plumego’s code style exists to enforce one thing:

Code must be easy to read, reason about, and modify years later.

Style is not about aesthetics.
It is about reducing cognitive load and preserving intent.

This document defines the expectations for all contributions.

Guiding Principles

All style rules derive from a few core principles:

  • Explicitness over cleverness
  • Clarity over brevity
  • Stability over novelty
  • Readability over reuse

If a style choice makes code shorter
but harder to understand,
it is rejected.

Go Code Style

Plumego follows standard Go conventions
plus additional constraints.

Formatting and Tooling

Mandatory:

  • gofmt for all Go code
  • Standard Go formatting rules
  • No custom formatting tools

Formatting discussions are not entertained.

Naming

Packages

  • Short
  • Singular
  • Descriptive
  • No abbreviations unless universally understood

Good:

context
router
middleware
response

Bad:

contexts
ctx
mw
resp

Types and Functions

  • Names must describe behavior, not intent
  • Avoid vague names like Manager, Handler, Processor
  • Prefer concrete verbs and nouns

Good:

RequestContext
RouteMatcher
WriteJSON

Bad:

ContextManager
HandleStuff
DoResponse

File Size and Scope

Guidelines:

  • Prefer small, focused files
  • One responsibility per file
  • Avoid “god files”

If a file grows beyond ~300 lines,
it usually needs to be split.

Functions

Length

  • Short functions are preferred
  • Functions longer than ~40 lines require justification

If a function is long because it is explicit, that is acceptable.
If it is long because it is clever, it is not.

Control Flow

Rules:

  • Avoid deeply nested logic
  • Prefer early returns
  • Make termination conditions obvious
  • Never hide control flow in helpers

If execution order is not obvious from reading the function,
the style is wrong.

Error Handling

Plumego is strict about errors.

Rules:

  • Always handle errors explicitly
  • Never ignore errors
  • Never log and swallow errors silently
  • Never convert errors implicitly

Good:

if err != nil {
    return err
}

Bad:

_ = doSomething()

Errors are part of the contract.

Comments

Comments are used to explain why, not what.

Rules:

  • Do not restate obvious code
  • Explain intent, constraints, or non-obvious decisions
  • Remove stale comments aggressively

Bad:

// increment i
i++

Good:

// We avoid caching here to preserve deterministic behavior.

Public APIs and Comments

All exported identifiers must have comments that:

  • Describe observable behavior
  • Define guarantees
  • Mention constraints

Avoid:

  • Marketing language
  • Implementation details
  • Vague descriptions

Public comments are part of the API contract.

Package Boundaries and Imports

Rules:

  • No cyclic dependencies
  • Respect dependency direction
  • Do not import internal packages outside allowed scope
  • Avoid “helper” packages that bypass boundaries

If a boundary feels inconvenient,
the boundary is probably doing its job.

Abstractions and Interfaces

Interfaces are powerful and dangerous.

Rules:

  • Do not introduce interfaces prematurely
  • Prefer concrete types until replacement is required
  • Keep interfaces small and behavior-focused

Bad:

type Service interface {
    DoEverything()
}

Good:

type RouteMatcher interface {
    Match(method, path string) (Route, bool)
}

Avoiding Cleverness

Plumego explicitly discourages:

  • Reflection-based logic
  • Metaprogramming tricks
  • Excessive generics
  • DSL-style APIs
  • Hidden callbacks

If code needs explanation to be understood,
it is probably too clever.

Documentation Style

Code style and documentation style are aligned.

Tone

Documentation must be:

  • Direct
  • Precise
  • Honest
  • Non-promotional

Avoid:

  • “Powerful”
  • “Elegant”
  • “Easy”
  • “Just works”

Describe behavior, not feelings.

Language Rules

Prefer:

  • “Must”, “Will”, “Does not”
  • Active voice
  • Concrete statements

Avoid:

  • “Should”, “Usually”, “Might”
  • Hedging language
  • Ambiguity

Ambiguous documentation is treated as incorrect.

Examples

Examples must:

  • Be realistic
  • Show explicit wiring
  • Avoid shortcuts
  • Avoid magic helpers

Examples that rely on undocumented behavior
will be rejected.

Tests Style

Tests are part of the codebase, not an afterthought.

Rules:

  • Tests must be readable
  • Prefer explicit setup
  • Avoid excessive mocking
  • Do not test internal implementation details

Tests should protect behavior, not structure.

What Is Explicitly Discouraged

Contributions will be rejected if they include:

  • Style-only refactors without justification
  • Renaming for personal preference
  • Abstraction for abstraction’s sake
  • Convenience helpers that hide behavior
  • Framework-like layers inside the framework

Consistency beats personal taste.

Review Enforcement

Style rules are enforced during review.

Reviewers may request:

  • Renaming
  • Simplification
  • De-abstraction
  • Documentation changes
  • Code removal

Style feedback is not optional.

Summary

Plumego’s code style exists to:

  • Preserve clarity
  • Reduce cognitive load
  • Make intent obvious
  • Enable safe evolution

If a change violates style,
it violates the framework’s guarantees.

  • Contribution Philosophy — why restraint matters
  • Code Structure — where code belongs
  • Decision Process — how changes are judged
  • Pull Request Guide — how code is reviewed

In Plumego, style is not decoration.

It is part of the architecture.