diff --git a/Style-Guide-for-Nim-Code.md b/Style-Guide-for-Nim-Code.md index 7543a6c..1085874 100644 --- a/Style-Guide-for-Nim-Code.md +++ b/Style-Guide-for-Nim-Code.md @@ -1,211 +1 @@ -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][] changes over time, this -style guide will too. - -[Python's style guide]: http://legacy.python.org/dev/peps/pep-0008/ - -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. - -- 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 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 - ``` - -### 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. - - ```nimrod - const - aConstant = 42 - FooBar = 4.2 - - var - aVariable = "Meep" - - 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. - - ```nimrod - type - Handle = int64 # Will be used most often - HandleRef = ref Handle # Will be used less often - ``` - -- Exception and Error types should have the "Error" suffix. - - ```nimrod - 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. Since - non-pure enum members can be referenced without full qualification - (in the form of ``MyEnum.fooValue``). - - ```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 - ``` - -- Uppercase acronyms (e.g. GPU) should be written in lowercase/capitalized: ``parseUrl`` rather than ``parseURL``, ``checkHttpHeader`` instead of ``checkHTTPHeader`` etc. - -### 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. - -- 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 - variables remain immutable, and gives those who read the code a better idea - of the code's purpose. - -- For new types, it is usually recommended to have both 'ref' and 'object' - versions of the type available for others to use. By making both variants - available for use, the type may be allocated both on the stack and the heap. - - -### 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. - - ```nimrod - type - ShortTuple = tuple[a: int, b: string] - - ReallyLongTuple = tuple - wordyTupleMemberOne: string - wordyTupleMemberTwo: int - wordyTupleMemberThree: double - ``` - -- 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 ( - timeRecieved: Time - errorCode: int - event: Event - ) - ``` - -- 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 - 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 - {.heyLookALongPragma.} = - ``` - -- 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. - readDirectoryChangesW( - directoryHandle.THandle, - buffer.start, - bufferSize.int32, - watchSubdir.WinBool, - filterFlags, - cast[ptr dword](nil), - cast[Overlapped](ol), - cast[OverlappedCompletionRoutine](nil) - ) - - - # Multiple arguments on new lines, aligned to the opening parenthesis - # Best suited for 'simple' procedure calls - startProcess(nimExecutable, currentDirectory, compilerArguments - environment, processOptions) - ``` +This document is now an official document hosted here: http://nim-lang.org/docs/nep1.html \ No newline at end of file