Nimrod Enhancement Proposal #1 - Standard Library Style Guide

Abstract
========
Although Nimrod, 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 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
over time, this style guide will too.

<br></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.

- 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 tedius. Furthermore, the large
  changes that re-alignment causes can make it harder to spot actual,
  program-altering changes when diffs are viewed.
    ```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
    ```

<br></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.

- Type identifiers should be in CamelCase. All other identifiers should be in
  pascalCase with the exception of constants which **may** use CamelCase but 
  are not required to.
    ```nimrod
    const aConstant = 42
    const FOO_BAR = 4.2

    var aVariable = "Meep"

    type FooBar = object
    ```

- 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 all versions.
  ```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 E_Base
  ```

- 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
      pcLinkToDir
      pcFile
      pcLinkToFile
    ```
  Non-pure enum values should use pascalCase whereas pure enum values should use CamelCase.

<br></br>
### 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
  readably.

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

<br></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
  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: TTime
      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
  ```

- 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[POverlapped](ol),
    cast[LPOverlappedCompletionRoutine](nil)
  )


  # Multiple arguments on new lines, aligned to the opening parenthesis
  # Best suited for 'simple' procedure calls
  startProcess(nimrodExecutable, currentDirectory, compilerArguments
               environment, processOptions)
  ```