nim-style-guide

Files (3)

• SKILL.md
• core_patterns.md · references/
• multiline_strings.md · references/

SKILL.md (first lines)

# Nim Style Guide

# Rules

## Formatting

- Indent blocks with 2 spaces and use spaces instead of tab characters.
- Keep lines at or below 100 characters.
- Use ordinary spacing instead of aligning columns by hand.
- Write range operators compactly: `a..b`, `a..<b`, and `a..^b`. Add spaces
  when an operand contains an operator, as in `a .. -3`.
- In `range` type constructors, use `..`: `range[0..n-1]` is valid;
  `range[0..<n]` is invalid.
- Indent wrapped declarations, calls, and conditions one extra level.

## Imports

- Use `std/...` imports for stdlib modules.
- Group imports from the same directory: `import std/[a, b, c]`, `import lib/[x, y, z]`.
- Use `from foo import bar, baz` when you only need a small API slice.
- `import` brings symbols into scope without qualification.
- `export` takes only the module name: `export baz`, not `export foo/bar/baz`.
- Use qualified `module.symbol` access only to resolve genuine name conflicts between imported modules.

## Naming

- Types use `PascalCase`.
- Procs, funcs, iterators, templates, vars, and fields use `camelCase`.
- Constants default to `PascalCase`; `camelCase` is also allowed.
- Use `ALL_UPPERCASE` only when preserving names from a C or C++ wrapper.
- Use normal word casing such as `parseUrl` and `httpStatus`.
- Do not stutter the type name into its fields; `Product.name`, not `Product.productName`.
- Use short names for parameters and locals that echo the type, as in `inv: Inventory` or `s: Session`.
- Give the most-used representation the base type name. Suffix the others with `Obj`, `Ref`, or `Ptr`.
- Suffix catchable exception types with `Error` and programming-bug defect types with `Defect`.
- For non-pure enums, prefix values such as `pcFile`. For pure enums, use `PascalCase`.
- Prefix mutable views with `m`, as in `mitems` and `mpairs`.
- Pair in-place and copied transforms as `reverse` and `reversed`. If the copy
  name already exists, suffix the in-place form with `In`, as in `replaceIn`.
- Name domain predicates subject-first, as in `fileExists`, not `existsFile`.
- Use established stdlib names when behavior matches: `initX`, `newX`, `find`,
  `contains`, `add`, `cmp`, `len`, `cap`, `items`, `pairs`, `incl`, and `excl`.
- Name a cheap, side-effect-free field getter `foo`. Use `getFoo` when the operation has side
  effects or is not O(1).
- Pair `foo` with `foo=` and `getFoo` with `setFoo`.
- Accessors may share the field's name, no collision.

## Proc, Func, Template, Macro

- Default to `proc`.
- Use `func` for pure helpers and pure accessors when checked purity helps.
- Use `template` when call-site substitution, lazy evaluation, or a
  control-flow abstraction is required.
- Prefer `proc` and `func` over `method`. Use `method` only when you need runtime dispatch.
- Prefer top-level helpers for reusable logic.
- Use a nested proc when the logic is truly local or when you want a closure.
- A nested proc may capture outer locals. If a nested proc must stay non-capturing, mark it `{.nimcall.}`.
- Use `macro` only when syntax transformation is required.
- Mark one-expression forwarders and field accessors `{.inline.}`.

## Calls, Locals, And Types

- Prefer compact wrapped calls over one-argument-per-line call blocks.
- Use UFCS when it reads like an accessor.
- Write `typeof(x)`, not the historical `type(x)`.
- Write enum values unqualified (`north`, not `Direction.north`); qualify only on ambiguity.
- Use `let` by default.
- Use `var` only for values that mutate.
- Keep local declarations close to first use.
- Keep public and reusable types at module scope.
- Group related fields with the same type when it improves readability.
- Initialize `result` explicitly; prefer object constructors
  (`TypeName(field: value)`) over field-by-field assignment.
- Omit fields that should keep their declared defaults.
- `T()` works only for objects; arrays use `arrayWith`, tuples use literals,
  strings/seqs use `""`/`@[]`, `default(T)` as fallback.

## Parsing-Sensitive Whitespace

These whitespace choices change how Nim parses code:

- **Attach `[` to a type name.**
  - `array[N, T]` compiles. `array [N, T]` does not.
  - The same applies to `seq[T]`, `Table[K, V]`, etc.

- **Attach `(` to a callable name for a parenthesized call.**
  - `foo(1, 2)` passes two `int` arguments.
  - `foo (1, 2)` passes a single `(int, int)` tuple. Nim treats the parenthesized comma-list as a tuple constructor.

- **Do not use command-call syntax with comparisons or nested calls.**
  - `foo 1 == 1` parses like `foo(1 == 1)`, not `foo(1) == 1`.
  - `outer(inner 1, 1)` parses as `outer(inner(1), 1)`, not `outer(inner(1, 1))`.

- **Use `[:T]` for explicit generic parameters in UFCS calls.**
  - `x.p[:T]()` rewrites to `p[T](x)`.
  - `x.p[T]()` parses as `(x.p)[T]()`, not a generic instantiation.

- **Group negated compound expressions.**
  - Parenthesize compound operands of `not`: `not a or b` parses as `(not a) or b`, so write `not (a or b)` and `not (x < y)`.
  - Write `x notin items`, not `not x in items`.

## Line Continuation

Nim has no line-continuation character. Break expressions after an operator
or comma, or within open delimiters such as `()`, `[]`, and `{}`. Indent the
continued line further than the statement that started it.

For constructs with a body, double indentation can distinguish continuation
lines from the body.

## Multiline Strings

- Use `"""..."""` triple-quoted literals instead of `"a\n" & "b\n"`
  concatenation for multiline values.
- Start with a newline right after `"""`. That newline is stripped, so the
  value is identical; the content aligns with the next line.

See `references/multiline_strings.md`.

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template