Updated NEP 1 (markdown)

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.
+- 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.