Nim Best Practices

3. proc vs func vs template vs macro vs iterator vs method

Rationale: Nim has six callable-like constructs; defaulting to the wrong one either hides bugs (side effects in something that looks pure) or reaches for far more machinery than the problem needs (a macro where a template would do, or a method where a plain proc would do).

func square(x: int): int = x * x          # compiler-verified pure

proc logAndSquare(x: int): int =           # proc: side effects (logging) permitted
  echo "squaring ", x
  x * x

template unless(cond: bool, body: untyped): untyped =
  if not cond: body                        # pasted inline at each call site, no proc-call overhead

iterator countTo(n: int): int =
  var i = 0
  while i <= n:
    yield i
    inc i

type
  Shape = ref object of RootObj
  Circle = ref object of Shape
    radius: float

method area(s: Shape): float {.base.} = 0.0
method area(s: Circle): float = 3.14159 * s.radius * s.radius

Why this works well in production: prefer static dispatch - plain proc overloading or generics with a type-class-style constraint - over method as the default polymorphism mechanism. Static dispatch is resolved and inlinable at compile time, avoids the runtime type-information and vtable-like overhead method requires, and does not force every participating type into a shared inheritance hierarchy; reach for method only when the set of concrete types genuinely is not known until runtime (e.g., a plugin registry). Prefer func over proc wherever a routine is genuinely pure - the compiler then guarantees purity for you, catching accidental side effects at compile time rather than in production. Prefer template over macro whenever simple substitution suffices; a macro's full AST access is powerful but harder to read, harder to debug, and unnecessary for most inlining/boilerplate-elimination use cases - see metaprogramming.md for the deep-dive on both.

4. Memory Management: ARC/ORC and Value Semantics

Rationale: Since Nim 2.0, ORC (ARC plus a back-up cycle collector) is the default memory management mode, replacing the deferred reference-counting tracing GC (--mm:refc) that was the default throughout Nim's 1.x line. Under ARC/ORC, the compiler inserts calls to compiler-synthesized (or user-overridden) =destroy, =copy, and =sink hooks at well-defined points - variable declaration, assignment, and routine calls - rather than relying on a background collector to reclaim memory eventually. The practical consequence: ordinary seq, string, and object values behave as value types with move semantics, not as hidden references. Passing a seq into a function that takes ownership, or returning one from a function, is compiled into a move (a cheap pointer/length transfer with the source invalidated) whenever the compiler can prove the source is not used again, and a real copy only when it cannot.

proc consume(data: sink seq[int]) =
  echo data.len              # `data` is owned here; the compiler moves rather than copies when possible

var big = @[1, 2, 3, 4, 5]
consume(big)                 # moved into `consume` - no deep copy, `big` should not be read afterward

Most ordinary Nim code needs no manual ref/pointer juggling at all: define plain object types, pass them by value or by var/sink parameter, and let the compiler manage lifetime. Reach for ref object (heap-allocated, ORC-cycle-collected) specifically when you need: genuinely shared mutable state across multiple owners, an explicit heap allocation (large objects you do not want copied, or objects whose address must stay stable), or a recursive/cyclic data structure (trees with parent pointers, doubly linked lists, graphs) where value semantics cannot express the shape at all.

type
  Node = ref object          # ref: heap-allocated, shared, ORC collects cycles automatically
    value: int
    next: Node                # a plain `object` (value type) could not express this self-reference

Why this works well in production: deterministic destruction means no GC pause to reason about under load, predictable latency, and RAII-style resource cleanup (closing files, releasing locks) exactly at scope exit - while still freeing the programmer from manual malloc/free bookkeeping for the common case. --mm:refc remains available (nim c --mm:refc) for legacy codebases or specific compatibility needs, but new code should target ORC (the default) or ARC explicitly.

5. Error Handling

Rationale: Nim's default error-handling mechanism is exceptions - raise SomeError.newException("message"), caught with try/except/finally - not return-value-based error codes. This is a deliberate design choice distinct from Rust's Result<T, E>-everywhere or Go's if err != nil, and it is easy for an LLM trained heavily on Rust/Go conventions to under-use.

type InsufficientInventoryError = object of CatchableError

proc reserveStock(available, requested: int) =
  if requested > available:
    raise newException(InsufficientInventoryError, "requested more than available")

try:
  reserveStock(available = 2, requested = 10)
except InsufficientInventoryError as e:
  echo "reservation failed: ", e.msg
finally:
  echo "reservation attempt complete"

For statically constraining which exceptions a routine may raise, use the {.raises.} effect-tracking pragma - an empty list is a compile-time guarantee that a routine raises nothing:

proc parsePositive(s: string): int {.raises: [ValueError].} =
  result = parseInt(s)          # parseInt itself may raise ValueError; anything else is a compile error
  if result <= 0:
    raise newException(ValueError, "must be positive")

proc pureAdd(a, b: int): int {.raises: [].} =
  a + b                           # compiler verifies this genuinely cannot raise

For expected, non-exceptional absence-of-value or recoverable-failure cases, prefer an explicit type over exceptions: the standard library's std/options (Option[T], some/none) for "a value might legitimately be absent," and the widely used community results package (arnetheduck/nim-results, installable via nimble install results) for a Result[T, E] value-or-error type modeled closely on Rust's Result. Prefer exceptions for genuinely exceptional, rarely-handled-at-the-call-site failures (a malformed config file aborting startup); prefer Option/Result for expected, frequently-handled-at-the-call-site outcomes (a lookup that legitimately may miss, a validation that legitimately may fail) where forcing the caller to handle both branches at the type level is valuable.

import std/options

proc findUser(id: int): Option[string] =
  if id == 1: some("alice") else: none(string)

let user = findUser(2)
if user.isSome:
  echo user.get()
else:
  echo "no such user"

6. The Implicit result Variable

Rationale: Every proc, func, method, or converter with a non-void return type has an implicitly declared variable named result, pre-initialized to that type's default (zero) value - 0 for integers, "" for strings, false for bool, nil for ref/ptr, an empty seq/default-initialized object otherwise. If control flow reaches the end of the routine body without an explicit return, the routine returns whatever result currently holds.

proc classify(x: int): string =
  if x < 0:
    result = "negative"
  elif x == 0:
    result = "zero"
  else:
    result = "positive"
  # no explicit `return` needed - `result`'s final value is returned

Two mistakes are common here, both worth checking for in generated code: forgetting result exists and declaring a redundant local variable that is then explicitly return-ed instead (harmless, but non-idiomatic and easy to get wrong when refactoring), and assuming result starts uninitialized - it does not; it always starts at the type's default zero value, so a routine that fails to assign it on every path silently returns that zero value rather than erroring, which can mask logic bugs.

# Bug: forgot to set result on one branch - silently returns "" (string default) instead of erroring
proc riskyClassify(x: int): string =
  if x > 0:
    result = "positive"
  # missing branch for x <= 0 - result stays "" here, easy to overlook in review

7. discard and the Discardable-by-Default Rule

Rationale: Nim requires every call whose return value is not used to be explicitly wrapped in a discard statement - an unused, non-void return value is a compile-time error (not merely a warning), unless the callee is marked {.discardable.}. This exists to catch the extremely common bug class of calling a function for its return value and then accidentally ignoring it (a failed-write check, an error code, a builder-pattern result used only for its side effect).

proc computeChecksum(data: string): int = data.len   # ordinary proc, return value matters

# computeChecksum("abc")          # compile error: value of type `int` has to be used (or discarded)
discard computeChecksum("abc")    # OK: explicitly acknowledges the value is intentionally unused

proc logEvent(msg: string): bool {.discardable.} =
  echo msg
  result = true

logEvent("startup complete")      # OK without discard - explicitly opted in via {.discardable.}

Why this works well in production: mark a proc {.discardable.} only when ignoring its result is a genuinely valid, common usage pattern (logging helpers, builder-style chained calls) - for everything else, the compiler-enforced discard requirement turns a whole class of "I forgot to check this" bugs into a compile error instead of a silent runtime mistake.

8. Compilation Flags for Development vs. Production

Rationale: Nim's runtime safety checks (bounds checking, integer overflow checking, nil dereference checking, and more) are on by default and during ordinary -d:release builds; only -d:danger strips them all for maximum throughput, and the memory-management mode and threading support are independent, explicitly selectable flags.

# nim.cfg or config.nims at the project root - checked in, not typed per-invocation
--mm:orc
--threads:on

# then simply:
#   nim c -d:release src/orders.nim     (safety checks kept, optimized)
#   nim c -d:danger  src/orders.nim     (all runtime checks stripped, fastest)

Why this works well in production: put these flags in a project-level nim.cfg/config.nims rather than expecting every developer or CI job to remember and retype them - this guarantees every build (local, CI, release) uses the same memory-management mode and threading configuration, and makes the release-vs-danger safety trade-off an explicit, reviewed project decision rather than an individual invocation's accident. See concurrency.md for the full implications of --threads:on combined with ARC/ORC.

Common Pitfalls & Anti-Patterns

This section lists a starter set; commonpitfalls.md is the canonical, exhaustive reference and should be consulted before trusting any nontrivial generated Nim code.

let items = @["a", "b", "c"]
for i in 0..<items.len:      # correct: indices 0, 1, 2 - matches items.len == 3
  echo items[i]
# for i in 0..items.len:     # bug: would include index 3, an out-of-bounds access

proc sum(xs: openArray[int]): int =   # accepts both seq[int] and array[N, int] with no copy
  for x in xs: result += x

echo sum(@[1, 2, 3])          # seq
echo sum([1, 2, 3])           # array - also works, no conversion needed