Best practices

Best Practices

This list is a community-maintained guide for some "best practice" suggestions. Written in the TLDR style, suggestions are in no particular order, should be beneficial to users with any level of Nim proficiency.

• Use 2 spaces indentation.
• Use func where possible.
• Use auto instead of any.
• Use self instead of this for specifying the main object argument in routines.
• Use const and let where possible.
• Put your types near the top of the file.
• Use import for public code instead of include.
• Use include for unittesting private code instead of import.
• Use testament instead of unittest.
• Use runnableExamples for code examples in the documentation.
• Use tuple to return multiple values of different types.
• Standard library imports should be prefixed with std/, like std/os, std/[strutils, sequtils], etc.
• Use when isMainModule: to specify code that'll only run if the source file is the main one.
• Design your code to work in-place, then use sugar.dup if you need to call it out-of-place.
• Prefer in-place functions, for example, sort instead of sorted where appropriate.
• Use options for optional types and optional returns, Option is lightweight.
• Use Natural or Positive as an argument or input type for non-negative integers.
• Use char to operate on single characters, for example "foo" & '\n' instead of "foo" & "\n".
• Annotating routines with {.deprecated.} will make the compiler print out all places where that routine is called.
• Procedures like echo, repr, astToStr, assert, expandMacros and the compiler switch --expandArc can be useful for debugging.
• In macros prefer to operate on the AST instead of using parseStmt and string operations.
• For designing new Macros, write the code you want to generate inside a dumpAstGen block and check the macro printed.
• Use string to represent strings, ASCII or Unicode, that are not raw binary blobs.
• Use seq[byte] to represent raw binary blobs, that are not strings ASCII or Unicode.
• Use func and proc even for OOP, do not use method because most code can be done without method.
• Use nimble init or a "repo template" to start a new project.
• Use code comments with FIXME, NOTE, OPTIMIZE, TODO so IDE, editors and GitHub Actions can read them.
• For documentation it is generally advised to use descriptive third person present tense with proper punctuation.
• For documentation the first paragraph of a doc comment must be a Summary, it must concisely define purpose and functionality.
• Do NOT use distinct tuple.
• Do NOT use float for money.
• Do NOT use discard on a Future.
• Do NOT use all caps on error messages.
• Do NOT add unused label names to block.
• Do NOT use exclamation marks on error messages.
• Do NOT use variable names on all uppercase, unless it is for FFI purposes.
• Do NOT use Natural nor Positive as return type for integers, use int or uint as return type instead.
• Do NOT use try blocks with lots of except branches, use explicit control flow instead.
• Do NOT repeat & too much to concatenate strings, use add instead.
• Do NOT repeat & too much to format strings, use strformat instead.
• Do NOT hardcode randomize() when coding API libs with random, let users call it, to avoid repeated calls to randomize().

See also:

• https://nim-lang.github.io/Nim/nep1.html