nim-wiki/NEP-1-:-Style-Guide-for-Nimrod-Code.md

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.

Style Guidelines
================

General
-------
- Type identifiers should be in CamelCase. All other identifiers should be in
  pascalCase. 
    ```nimrod
    const aConstant = 42

    var aVariable = "Meep"

    type FooBar = object
    ```

- Members of enums should have an identifying prefix, such as an abbreviation
  of the enum's name.
    ```nimrod
    type PathComponent = enum
      pcDir
      pcLinkToDir
      pcFile
      pcLinkToFile
    ```

- Lines should be no longer than 80 characters

- 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
  backends to perform special optimizations

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

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

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