diff options
| -rw-r--r-- | doc/nep1.rst | 95 |
1 files changed, 36 insertions, 59 deletions
diff --git a/doc/nep1.rst b/doc/nep1.rst index a2d7ab3f3..d44265193 100644 --- a/doc/nep1.rst +++ b/doc/nep1.rst @@ -1,7 +1,7 @@ ============================================== Nim Enhancement Proposal #1 - Standard Library Style Guide ============================================== -:Author: Clay Sweetser +:Author: Clay Sweetser, Dominik Picheta :Version: |nimversion| .. contents:: @@ -76,11 +76,13 @@ changed in the future. 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" + var aVariable = "Meep" # Variables must start with a lowercase letter. + # Types must start with an uppercase letter. type FooBar = object @@ -95,13 +97,16 @@ changed in the future. .. code-block:: nim type - Handle = int64 # Will be used most often + 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. @@ -112,6 +117,7 @@ changed in the future. pcLinkToDir pcFile pcLinkToFile + - Non-pure enum values should use camelCase whereas pure enum values should use PascalCase. @@ -122,91 +128,62 @@ changed in the future. 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 tread them as what they are: Real words. So it's ``parseUrl`` rather than ``parseURL``, ``checkHttpHeader`` instead of ``checkHTTPHeader`` etc. + 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 only be used when its control-flow properties - are required. Use a procedure's implicit 'result' variable instead. This - improves readability. +- 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. -- Prefer to return `[]` and `""` instead of `nil`, or throw an exception if - that is appropriate. + .. 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 +- 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. +- Tuples which are longer than one line should indent their parameters to + align with the parameters above it. .. code-block:: nim type - ShortTuple = tuple[a: int, b: string] + LongTupleA = tuple[wordyTupleMemberOne: int, wordyTupleMemberTwo: string, + wordyTupleMemberThree: float] - 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. +- Similarly, any procedure and procedure type declarations that are longer# + than one line should do the same thing. .. code-block:: nim 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). + EventCallback = proc (timeReceived: Time, errorCode: int, event: Event, + output: var string) - .. code-block:: nim 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. + +- Multi-line procedure calls should continue on the same column as the opening + parenthesis (like multi-line procedure declarations). .. code-block:: nim - # 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) + environment, processOptions) \ No newline at end of file |