cadey
/
nim-wiki
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Updated NEP 1 : Style Guide for Nim Code (markdown)

This commit is contained in:
Flaviu Tamas 2015-01-11 13:41:51 -05:00
parent d72cdf1b83
commit fe38edb7c5
1 changed files with 84 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
NEP 1 : Style Guide for Nim Code.md
View File

@ -1,17 +1,18 @@
Nim Enhancement Proposal #1 - Standard Library Style Guide #Nim Enhancement Proposal #1 - Standard Library Style Guide
Abstract Abstract
======== ========
Although Nim, through its flexible AST and case-sensitivity settings, Although Nim, through its flexible AST and case-sensitivity settings, supports a
supports a variety of code and formatting styles, it is nevertheless beneficial variety of code and formatting styles, it is nevertheless beneficial that
that certain community efforts, such as the standard library, should follow certain community efforts, such as the standard library, should follow a
a consistent set of style guidelines when suitable. This enhancement consistent set of style guidelines when suitable. This enhancement proposal aims
proposal aims to list a series of guidelines that the standard library should to list a series of guidelines that the standard library should follow. Note
follow. Note that these are *guidelines* only. The nature of Nim being that these are *guidelines* only. The nature of Nim being as flexible as it is,
as flexible as it is, there will be parts of this style guide that don't make there will be parts of this style guide that don't make sense in certain
sense in certain contexts. Furthermore, just as contexts. Furthermore, just as [Python's style guide][] changes over time, this
[Python's style guide](http://legacy.python.org/dev/peps/pep-0008/) changes style guide will too.
over time, this style guide will too.
[Python's style guide]: http://legacy.python.org/dev/peps/pep-0008/
Style Guidelines Style Guidelines
================ ================
@ -21,54 +22,57 @@ Style Guidelines
has smaller chunks to process. has smaller chunks to process.
- 2 spaces should be used for indentation of blocks; tabstops are not allowed - 2 spaces should be used for indentation of blocks; tabstops are not allowed
(the compiler enforces this). Using spaces means that the appearance of (the compiler enforces this). Using spaces means that the appearance of code
code is more consistant across editors. Unlike spaces, tabstop width varies is more consistent across editors. Unlike spaces, tabstop width varies across
across editors, and not all editors provide means of changing this width. editors, and not all editors provide means of changing this width.
- Although use of whitespace for stylistic reasons other than the ones endorsed - 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. 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 Not all editors support automatic alignment of code sections, and re-aligning
long sections of code by hand can quickly become tedious. long sections of code by hand can quickly become tedious.
```nimrod
# This is bad, as the next time someone comes ```nimrod
# to edit this code block, they # This is bad, as the next time someone comes
# must re-align all the assignments again: # to edit this code block, they
type # must re-align all the assignments again:
WordBool* = int16 type
CalType* = int WordBool* = int16
... # 5 lines later CalType* = int
CalId* = int ... # 5 lines later
LongLong* = int64 CalId* = int
LongLongPtr* = ptr LongLong LongLong* = int64
``` LongLongPtr* = ptr LongLong
```
### Naming Conventions ### ### Naming Conventions ###
Note: While the rules outlined below are the *current* naming conventions, Note: While the rules outlined below are the *current* naming conventions,
these conventions have not always been in place. Previously, the naming these conventions have not always been in place. Previously, the naming
conventions for identifiers followed the Pascal tradition of prefixes conventions for identifiers followed the Pascal tradition of prefixes which
which indicated the base type of the identifier - PFoo for pointer and reference 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 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 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 convention. Such style remains in place purely for legacy reasons, and will be
be changed in the future. changed in the future.
- Type identifiers should be in camelCase. All other identifiers should be in - Type identifiers should be in camelCase. All other identifiers should be in
camelCase with the exception of constants which **may** use PascalCase but camelCase with the exception of constants which **may** use PascalCase but
are not required to. are not required to.
```nimrod
const aConstant = 42
const FooBar = 4.2
var aVariable = "Meep" ```nimrod
const aConstant = 42
const FooBar = 4.2
type FooBar = object var aVariable = "Meep"
```
type FooBar = object
```
- 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 all versions.
- 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 all versions.
```nimrod ```nimrod
type type
handle = int64 # Will be used most often handle = int64 # Will be used most often
@ -76,6 +80,7 @@ be changed in the future.
``` ```
- Exception and Error types should have the "Error" suffix. - Exception and Error types should have the "Error" suffix.
```nimrod ```nimrod
type UnluckyError = object of E_Base type UnluckyError = object of E_Base
``` ```
@ -83,35 +88,39 @@ be changed in the future.
- Unless marked with the `{.pure.}` pragma, members of enums should have an - Unless marked with the `{.pure.}` pragma, members of enums should have an
identifying prefix, such as an abbreviation of the enum's name. Since identifying prefix, such as an abbreviation of the enum's name. Since
non-pure enum members can be referenced without non-pure enum members can be referenced without
```nimrod
type PathComponent = enum ```nimrod
pcDir type PathComponent = enum
pcLinkToDir pcDir
pcFile pcLinkToDir
pcLinkToFile pcFile
``` pcLinkToFile
Non-pure enum values should use camelCase whereas pure enum values should use PascalCase. ```
```nimrod
type PathComponent {.pure.} = enum Non-pure enum values should use camelCase whereas pure enum values should use
Dir PascalCase.
LinkToDir
File ```nimrod
LinkToFile type PathComponent {.pure.} = enum
``` Dir
LinkToDir
File
LinkToFile
```
### Coding Conventions ### ### Coding Conventions ###
- The 'return' statement should only be used when it's control-flow properties - The 'return' statement should only be used when it's control-flow properties
are required. Use a procedures implicit 'result' variable instead. This improves are required. Use a procedures implicit 'result' variable instead. This
readability. improves readability.
- Prefer to return `[]` and `""` instead of `nil`, or throw an exception if that - Prefer to return `[]` and `""` instead of `nil`, or throw an exception if
is appropriate. that is appropriate.
- Use a proc when possible, only using the more powerful facilities of macros, - Use a proc when possible, only using the more powerful facilities of macros,
templates, iterators, and converters when necessary. templates, iterators, and converters when necessary.
- Use the 'let' statement (not the var statement) when declaring variables - Use the 'let' statement (not the var statement) when declaring variables that
that do not change within their scope. Using the let statement ensures 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 variables remain immutable, and gives those who read the code a better idea
of the code's purpose. of the code's purpose.
@ -119,8 +128,8 @@ be changed in the future.
### Conventions for multi-line statements and expressions ### ### Conventions for multi-line statements and expressions ###
- Any tuple type declarations that are longer than one line should use the - Any tuple type declarations that are longer than one line should use the
regular object type layout instead. This enhances the readability of the regular object type layout instead. This enhances the readability of the
tuple declaration by splitting its members information across multiple tuple declaration by splitting its members information across multiple lines.
lines.
```nimrod ```nimrod
type type
ShortTuple = tuple[a: int, b: string] ShortTuple = tuple[a: int, b: string]
@ -133,6 +142,7 @@ be changed in the future.
- Similarly, any procedure type declarations that are longer than one line - Similarly, any procedure type declarations that are longer than one line
should be formatted in the style of a regular type. should be formatted in the style of a regular type.
```nimrod ```nimrod
type type
EventCallback = proc ( EventCallback = proc (
@ -144,21 +154,23 @@ be changed in the future.
- Multi-line procedure declarations/argument lists should continue on the same - Multi-line procedure declarations/argument lists should continue on the same
column as the opening brace. This style is different from that of procedure column as the opening brace. This style is different from that of procedure
type declarations in order to distinguish between the heading of a type declarations in order to distinguish between the heading of a procedure
procedure and its body. If the procedure name is too long to make this style and its body. If the procedure name is too long to make this style
convenient, then one of the styles for multi-line procedure calls (or convenient, then one of the styles for multi-line procedure calls (or
consider renaming your procedure). consider renaming your procedure).
```nimrod ```nimrod
proc lotsOfArguments(argOne: string, argTwo: int, argThree:float proc lotsOfArguments(argOne: string, argTwo: int, argThree:float
argFour: proc(), argFive: bool): int argFour: proc(), argFive: bool): int
``` ```
- Multi-line procedure calls should either have one argument per line - Multi-line procedure calls should either have one argument per line (like
(like multi-line type declarations) or continue on the same multi-line type declarations) or continue on the same column as the opening
column as the opening parenthesis (like multi-line procedure declarations). parenthesis (like multi-line procedure declarations). It is suggested that
It is suggested that the former style be used for procedure calls with the former style be used for procedure calls with complex argument
complex argument structures, and the latter style for procedure calls with structures, and the latter style for procedure calls with simpler argument
simpler argument structures. structures.
```nimrod ```nimrod
# Each argument on a new line, like type declarations # Each argument on a new line, like type declarations
# Best suited for 'complex' procedure calls. # Best suited for 'complex' procedure calls.