1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
==============================================
Nim Enhancement Proposal #1 - Standard Library Style Guide
==============================================
:Author: Clay Sweetser, Dominik Picheta
:Version: |nimversion|
.. contents::
Introduction
============
Although Nim supports a variety of code and formatting styles, it is
nevertheless beneficial that certain community efforts, such as the standard
library, should follow a consistent set of style guidelines when suitable.
This enhancement proposal aims to list a series of guidelines that the standard
library should follow.
Note that there can be exceptions to these rules. Nim being as flexible as it
is, there will be parts of this style guide that don't make sense in certain
contexts. Furthermore, just as
`Python's style guide<http://legacy.python.org/dev/peps/pep-0008/>`_ changes
over time, this style guide will too.
These rules will only be enforced for contributions to the Nim
codebase and official projects, such as the Nim compiler, the standard library,
and the various official tools such as C2Nim.
----------------
Style Guidelines
----------------
Spacing and Whitespace Conventions
-----------------------------------
- Lines should be no longer than 80 characters. Limiting the amount of
information present on each line makes for more readable code - the reader
has smaller chunks to process.
- Two spaces should be used for indentation of blocks; tabstops are not allowed
(the compiler enforces this). Using spaces means that the appearance of code
is more consistent across editors. Unlike spaces, tabstop width varies across
editors, and not all editors provide means of changing this width.
- Although use of whitespace for stylistic reasons other than the ones endorsed
by this guide are allowed, careful thought should be put into such practices.
Not all editors support automatic alignment of code sections, and re-aligning
long sections of code by hand can quickly become tedious.
.. code-block:: nim
# This is bad, as the next time someone comes
# to edit this code block, they
# must re-align all the assignments again:
type
WordBool* = int16
CalType* = int
... # 5 lines later
CalId* = int
LongLong* = int64
LongLongPtr* = ptr LongLong
Naming Conventions
-------------------------
Note: While the rules outlined below are the *current* naming conventions,
these conventions have not always been in place. Previously, the naming
conventions for identifiers followed the Pascal tradition of prefixes which
indicated the base type of the identifier - PFoo for pointer and reference
types, TFoo for value types, EFoo for exceptions, etc. Though this has since
changed, there are many places in the standard library which still use this
convention. Such style remains in place purely for legacy reasons, and will be
changed in the future.
- Type identifiers should be in PascalCase. All other identifiers should be in
camelCase with the exception of constants which **may** use PascalCase but
are not required to.
.. code-block:: nim
# Constants can start with either a lower case or upper case letter.
const aConstant = 42
const FooBar = 4.2
var aVariable = "Meep" # Variables must start with a lowercase letter.
# Types must start with an uppercase letter.
type
FooBar = object
For constants coming from a C/C++ wrapper, ALL_UPPERCASE are allowed, but ugly.
(Why shout CONSTANT? Constants do no harm, variables do!)
- When naming types that come in value, pointer, and reference varieties, use a
regular name for the variety that is to be used the most, and add a "Obj",
"Ref", or "Ptr" suffix for the other varieties. If there is no single variety
that will be used the most, add the suffixes to the pointer variants only. The
same applies to C/C++ wrappers.
.. code-block:: nim
type
Handle = object # Will be used most often
fd: int64
HandleRef = ref Handle # Will be used less often
- Exception and Error types should have the "Error" suffix.
.. code-block:: nim
type
UnluckyError = object of Exception
- Unless marked with the `{.pure.}` pragma, members of enums should have an
identifying prefix, such as an abbreviation of the enum's name.
.. code-block:: nim
type
PathComponent = enum
pcDir
pcLinkToDir
pcFile
pcLinkToFile
- Non-pure enum values should use camelCase whereas pure enum values should use
PascalCase.
.. code-block:: nim
type
PathComponent {.pure.} = enum
Dir
LinkToDir
File
LinkToFile
- In the age of HTTP, HTML, FTP, TCP, IP, UTF, WWW it is foolish to pretend
these are somewhat special words requiring all uppercase. Instead treat them
as what they are: Real words. So it's ``parseUrl`` rather than
``parseURL``, ``checkHttpHeader`` instead of ``checkHTTPHeader`` etc.
Coding Conventions
------------------
- The 'return' statement should ideally be used when its control-flow properties
are required. Use a procedure's implicit 'result' variable whenever possible.
This improves readability.
.. code-block:: nim
proc repeat(text: string, x: int): string =
result = ""
for i in 0 .. x:
result.add($i)
- Use a proc when possible, only using the more powerful facilities of macros,
templates, iterators, and converters when necessary.
- Use the ``let`` statement (not the ``var`` statement) when declaring variables that
do not change within their scope. Using the ``let`` statement ensures that
variables remain immutable, and gives those who read the code a better idea
of the code's purpose.
Conventions for multi-line statements and expressions
-----------------------------------------------------
- Tuples which are longer than one line should indent their parameters to
align with the parameters above it.
.. code-block:: nim
type
LongTupleA = tuple[wordyTupleMemberOne: int, wordyTupleMemberTwo: string,
wordyTupleMemberThree: float]
- Similarly, any procedure and procedure type declarations that are longer#
than one line should do the same thing.
.. code-block:: nim
type
EventCallback = proc (timeReceived: Time, errorCode: int, event: Event,
output: var string)
proc lotsOfArguments(argOne: string, argTwo: int, argThree: float
argFour: proc(), argFive: bool): int
{.heyLookALongPragma.} =
- Multi-line procedure calls should continue on the same column as the opening
parenthesis (like multi-line procedure declarations).
.. code-block:: nim
startProcess(nimExecutable, currentDirectory, compilerArguments
environment, processOptions)
|