Updated NEP 1 : Style Guide for Nimrod Code (markdown)

NEP-1-:-Style-Guide-for-Nimrod-Code.md

@@ -13,11 +13,48 @@ 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.
 
+<br>
 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 consistant across editors. Unlike spaces, tabstop width varies
+  across editors, and not all editors provide means of changing this width.
+
+- Use of extra whitespace for alignment in ways other than dictated by the
+  style guide is discouraged. Manual alignment and re-alignment of code is
+  tedious, and not all editors have support for auto-alignment of code
+  sections, plus re-alignment of code blocks causes larger, less distinct
+  code diffs.
+  ```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
+    CalId*       = int
+    LongLong*    = int64
+    LongLongPtr* = ptr LongLong
+  ```
+<br>
+
+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 identifer - 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.
 
-General
--------
 - Type identifiers should be in CamelCase. All other identifiers should be in
   pascalCase. 
     ```nimrod
@@ -27,9 +64,28 @@ General
 
     type FooBar = object
     ```
+<br>
 
-- Members of enums should have an identifying prefix, such as an abbreviation
+- When naming types that come in value, pointer, and reference varieties,
-  of the enum's name.
+  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
+    handleRef = ref handle # Will be used less often
+  ```
+<br>
+
+- Exception and Error types should have the "Error" suffix.
+  ```nimrod
+  type unluckyError = object of E_Base
+  ```
+<br>
+
+- 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
@@ -37,13 +93,10 @@ General
       pcFile
       pcLinkToFile
     ```
+<br>
 
-- Lines should be no longer than 80 characters
+Coding Conventions
-
+----------------
-- 2 spaces should be used for indentation. Although one can use tabstops for
-  indentation through use of template filters, this considered an unnecessary
-  hack.
-
 - 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
@@ -53,7 +106,10 @@ General
   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.
+<br>
 
+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
@@ -67,6 +123,7 @@ General
       wordyTupleMemberTwo: int
       wordyTupleMemberThree: double
   ```
+<br>
 
 - Similarly, any procedure type declarations that are longer than one line
   should be formatted in the style of a regular type.
@@ -78,15 +135,19 @@ General
       event: Event
     )
   ```
+<br>
 
 - 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.
+  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
+  proc lotsOfArguments(argOne: string, argTwo: int, argThree:float
-                       argFour: proc(), argFive: bool): int
+                       argFour: proc(), argFive:bool): int
   ```
+<br>
 
 - Multi-line procedure calls should either have one argument per line 
   (like multi-line type declarations) or continue on the same
@@ -113,42 +174,4 @@ General
   # Best suited for 'simple' procedure calls
   startProcess(nimrodExecutable, currentDirectory, compilerArguments
                environment, processOptions)
-  ```
-
-- Use of extra whitespace for alignment is discouraged. This is not
-  necessarily because such a alignment is bad, but because of the varying
-  support editors have for auto-alignment of text, and the fact that manual
-  alignment and re-alignment can be quite time consuming.
-  
-  Incorrect:
-  
-  ```nimrod
-  type
-    WORDBOOL*   = int16
-    CALTYPE*    = int
-    CALID*      = int
-    CCHAR*      = char
-    TCOLORREF*  = COLORREF
-    WINT*       = int32
-    PINTEGER*   = ptr int32
-    PBOOL*      = ptr WINBOOL
-    LONGLONG*   = int64
-    PLONGLONG*  = ptr LONGLONG
-    LPLONGLONG* = ptr LONGLONG
-  ```
-
-  Correct:
-  ```nimrod
-  type
-    WORDBOOL* = int16
-    CALTYPE* = int
-    CALID* = int
-    CCHAR* = char
-    TCOLORREF* = COLORREF
-    WINT* = int32
-    PINTEGER* = ptr int32
-    PBOOL* = ptr WINBOOL
-    LONGLONG* = int64
-    PLONGLONG* = ptr LONGLONG
-    LPLONGLONG* = ptr LONGLONG
   ```