diff --git a/NEP-1.md b/NEP-1.md index 0da3591..b9e907a 100644 --- a/NEP-1.md +++ b/NEP-1.md @@ -10,7 +10,7 @@ proposal aims to list a series of guidelines that the standard library should follow. Note that these are *guidelines* only. The nature of Nimrod 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 +(Python's style guide)[http://legacy.python.org/dev/peps/pep-0008/] changes over time, this style guide will too. Style Guidelines @@ -18,17 +18,80 @@ Style Guidelines General ------- -- All identifiers, except for types, should be in pascalCase. Type identifiers - should be in CamelCase. +- Type identifiers should be in CamelCase. All identifiers should be in + pascalCase. + ``` + const + aConstant = 42 -- Members of enums should have an identifying prefix before their - names. For example, the PathComponent enum in the os module contains the - pcFile member, which, like the other members, has the 'pc' - (standing for PathComponent) prefix before its name. An exception to this rule exists when using ``pure`` enums. + var + aVariable = "Meep" + + type + FooBar = object + ``` + +- Members of enums should have an identifying prefix, such as an abbreviation + of the enum's name. + ``` + type PathComponent = enum + pcDir + pcLinkToDir + pcFile + pcLinkToFile + ``` - Lines should be no longer than 80 characters -- 2 spaces should be used for indentation. +- 2 spaces should be used for indentation. Although one can use tabstops for + indentation through use of template filters, this considered an unneccessary + hack. -- The 'result' variable should be used whenever possible. 'return' should only - be used when it's flow control effects are needed. \ No newline at end of file +- The 'return' statement should only be used when it's control-flow properties + are required. Use a procedures implicit 'result' variable instead. Using the + implicit result variables allows both the Nimrod compiler and its various + backends to perform special optimizations + +- Use the 'let' statement (not the var statement) when declarding 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. + +- 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. + ``` + 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. + ``` + type + EventCallback = proc ( + timeRecieved: TTime + errorCode: int + event: Event + ) + ``` + +- Multi-line procedure declarations/argument lists should continue on the same + column as the preceding brace. This style is different from that of procedure + type declarations in order to prevent confusion between the heading of a + procedure and its body. + ``` + proc lotsOfArguments(argOne: string, argTwo: int, argThree:float + argFour: proc(), argFive:bool): int + ``` + +- Use of extra whitespace for alignment is generally discouraged. This is not + neccessarily because such a style is bad, but because of the varying support + editors have for auto aligning blocks of code, and the fact that manually + aligning and re-aligning parts of code can be quite time consuming. \ No newline at end of file