From fe38edb7c54d99be11853f25b820d2ffafa8887e Mon Sep 17 00:00:00 2001 From: Flaviu Tamas Date: Sun, 11 Jan 2015 13:41:51 -0500 Subject: [PATCH] Updated NEP 1 : Style Guide for Nim Code (markdown) --- NEP 1 : Style Guide for Nim Code.md | 156 +++++++++++++++------------- 1 file changed, 84 insertions(+), 72 deletions(-) diff --git a/NEP 1 : Style Guide for Nim Code.md b/NEP 1 : Style Guide for Nim Code.md index 5ba82ff..2fcef4b 100644 --- a/NEP 1 : Style Guide for Nim Code.md +++ b/NEP 1 : Style Guide for Nim Code.md @@ -1,17 +1,18 @@ -Nim Enhancement Proposal #1 - Standard Library Style Guide +#Nim Enhancement Proposal #1 - Standard Library Style Guide Abstract ======== -Although Nim, through its flexible AST and case-sensitivity settings, -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 these are *guidelines* only. The nature of 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. +Although Nim, through its flexible AST and case-sensitivity settings, 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 these are *guidelines* only. The nature of 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][] changes over time, this +style guide will too. + +[Python's style guide]: http://legacy.python.org/dev/peps/pep-0008/ Style Guidelines ================ @@ -21,54 +22,57 @@ Style Guidelines has smaller chunks to process. - 2 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 consistant across editors. Unlike spaces, tabstop width varies - across editors, and not all editors provide means of changing this width. + (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. - ```nimrod - # 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 - ``` + + ```nimrod + # 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 +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. +convention. Such style remains in place purely for legacy reasons, and will be +changed in the future. - 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. - ```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 type 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. + ```nimrod 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 identifying prefix, such as an abbreviation of the enum's name. Since non-pure enum members can be referenced without - ```nimrod - type PathComponent = enum - pcDir - pcLinkToDir - pcFile - pcLinkToFile - ``` - Non-pure enum values should use camelCase whereas pure enum values should use PascalCase. - ```nimrod - type PathComponent {.pure.} = enum - Dir - LinkToDir - File - LinkToFile - ``` + + ```nimrod + type PathComponent = enum + pcDir + pcLinkToDir + pcFile + pcLinkToFile + ``` + + Non-pure enum values should use camelCase whereas pure enum values should use + PascalCase. + + ```nimrod + type PathComponent {.pure.} = enum + Dir + LinkToDir + File + LinkToFile + ``` ### Coding Conventions ### - The 'return' statement should only be used when it's control-flow properties - are required. Use a procedures implicit 'result' variable instead. This improves - readability. + are required. Use a procedures implicit 'result' variable instead. This + improves readability. -- Prefer to return `[]` and `""` instead of `nil`, or throw an exception if that - is appropriate. +- Prefer to return `[]` and `""` instead of `nil`, or throw an exception if + that is appropriate. - 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 +- 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. @@ -119,8 +128,8 @@ be changed in the future. ### Conventions for multi-line statements and expressions ### - Any tuple type declarations that are longer than one line should use the regular object type layout instead. This enhances the readability of the - tuple declaration by splitting its members information across multiple - lines. + tuple declaration by splitting its members information across multiple lines. + ```nimrod type 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 should be formatted in the style of a regular type. + ```nimrod type EventCallback = proc ( @@ -144,21 +154,23 @@ be changed in the future. - Multi-line procedure declarations/argument lists should continue on the same column as the opening brace. This style is different from that of procedure - type declarations in order to distinguish between the heading of a - procedure and its body. If the procedure name is too long to make this style + type declarations in order to distinguish between the heading of a procedure + 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 consider renaming your procedure). + ```nimrod proc lotsOfArguments(argOne: string, argTwo: int, argThree:float argFour: proc(), argFive: bool): int ``` -- Multi-line procedure calls should either have one argument per line - (like multi-line type declarations) or continue on the same - column as the opening parenthesis (like multi-line procedure declarations). - It is suggested that the former style be used for procedure calls with - complex argument structures, and the latter style for procedure calls with - simpler argument structures. +- Multi-line procedure calls should either have one argument per line (like + multi-line type declarations) or continue on the same column as the opening + parenthesis (like multi-line procedure declarations). It is suggested that + the former style be used for procedure calls with complex argument + structures, and the latter style for procedure calls with simpler argument + structures. + ```nimrod # Each argument on a new line, like type declarations # Best suited for 'complex' procedure calls.