-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Best practices
Juan Carlos edited this page Oct 26, 2021
·
7 revisions
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
funcwhere possible. - Use
autoinstead ofany. - Use
selfinstead ofthisfor specifying the main object argument in routines. - Use
constandletwhere possible. - Put your types near the top of the file.
- Use
importfor public code instead ofinclude. - Use
includefor unittesting private code instead ofimport. - Use
runnableExamplesfor code examples in the documentation. - Use
tupleto return multiple values of different types. - Standard library imports should be prefixed with
std/, likestd/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.dupif you need to call it out-of-place. - Prefer in-place functions, for example,
sortinstead ofsortedwhere appropriate. - Use
optionsfor optional types and optional returns. - Use
NaturalorPositiveas an argument or input type for non-negative integers. - Use
charto 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,expandMacrosand the compiler switch--expandArccan be useful for debugging. - In macros prefer to operate on the AST instead of using
parseStmtand string operations. - For designing new macros write the desired result manually and then use
dumpAstGento get macro code that will generate the same code. - Use
stringto represent strings of any kind (Nim strings are not encoded in any way) - NOT for binary blobs. - Use
seq[byte]to represent raw binary blobs. - Prefer to use
funcand/orproceven for OOP, use interface-like libraries (for example iface instead ofmethodunless there's no way around it. - Use
nimble initor a "repo template" like nimtemplate to start a new project. - Try to use
FIXME,NOTE,OPTIMIZE,TODOin relevant code comments so that editors and GitHub Actions can read them. - For documentation it is generally preferred to use descriptive third person present tense with proper punctuation.
- For documentation the first paragraph of a doc comment must be a summary, it should concisely define the purpose and functionality of the module/library.
-
Do NOT use
distinct tuple. -
Do NOT use
floatfor things that need to be precise (like money), instead consider using decimal. -
Do NOT use
discardon aFuture. -
Do NOT add label names to the
blockstatement if you don't use them. - Do NOT write error messages in ALL_CAPS.
- Do NOT use exclamation marks in error messages.
- Do NOT name your variables in ALL_CAPS unless it's required for FFI purposes.
-
Do NOT use
NaturalorPositiveas a return type for integers, useintoruintinstead. -
Do NOT use
tryblocks with a lot ofexceptbranches, use explicit control flow instead. -
Do NOT repeat
&too much for string concatenation, useaddinstead. -
Do NOT repeat
&too much to string formatting, usestd/strformatinstead. -
Do NOT call
randomize()in your libraries that usestd/random, users should call it themselves.
See also:
Intro
Getting Started
- Install
- Docs
- Curated Packages
- Editor Support
- Unofficial FAQ
- Nim for C programmers
- Nim for Python programmers
- Nim for TypeScript programmers
- Nim for D programmers
- Nim for Java programmers
- Nim for Haskell programmers
Developing
- Build
- Contribute
- Creating a release
- Compiler module reference
- Consts defined by the compiler
- Debugging the compiler
- GitHub Actions/Travis CI/Circle CI/Appveyor
- GitLab CI setup
- Standard library and the JavaScript backend
Misc