Merge pull request #3098 from Varriount/add-nep1

Add NEP1 to documentation.

6 files changed, 224 insertions, 3 deletions

diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg
index e036c3b9a..57d4cc988 100644
--- a/config/nimdoc.cfg
+++ b/config/nimdoc.cfg
@@ -578,7 +578,7 @@ pre {
   box-sizing: border-box;
   min-width: calc(100% - 19.5px);
   padding: 9.5px;
-  margin: 0 10px 0px 10px;
+  margin: 0.25em 10px 0.25em 10px;
   font-size: 14px;
   line-height: 20px;
   white-space: pre !important;
@@ -981,6 +981,10 @@ div.align-right {
 
 /* div.align-center * { */
 /*   text-align: left } */
+
+ul.simple > li {
+  margin-bottom: 0.5em }
+
 ol.simple, ul.simple {
   margin-bottom: 1em; }
 
diff --git a/doc/nep1.txt b/doc/nep1.txt
new file mode 100644
index 000000000..e44ec8382
--- /dev/null
+++ b/doc/nep1.txt
@@ -0,0 +1,208 @@
+==============================================
+Nim Enhancement Proposal #1 - Standard Library Style Guide
+==============================================
+:Author: Clay Sweetser
+:Version: |nimversion|
+
+.. contents::
+
+
+Introduction
+============
+Although Nim 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 there can be exceptions to these rules. Nim 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. 
+
+These rules will only be enforced for contributions to the Nim
+codebase and official projects, such as the Nim compiler, the standard library,
+and the various official tools such as C2Nim.
+
+----------------
+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.
+
+- Two 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 consistent 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 tedious.
+
+  .. code-block:: nim
+    # 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
+
+
+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 identifier - 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 PascalCase. All other identifiers should be in
+  camelCase with the exception of constants which **may** use PascalCase but
+  are not required to.
+
+  .. code-block:: nim
+    const aConstant = 42
+    const FooBar = 4.2
+
+    var aVariable = "Meep"
+
+    type FooBar = object
+
+  For constants coming from a C/C++ wrapper, ALL_UPPERCASE are allowed, but ugly.
+  (Why shout CONSTANT? Constants do no harm, variables do!)
+
+- 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 the pointer variants only. The
+  same applies to C/C++ wrappers.
+
+  .. code-block:: nim
+    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.
+
+  .. code-block:: nim
+    type UnluckyError = object of Exception
+- Unless marked with the `{.pure.}` pragma, members of enums should have an
+  identifying prefix, such as an abbreviation of the enum's name.
+
+  .. code-block:: nim
+    type PathComponent = enum
+      pcDir
+      pcLinkToDir
+      pcFile
+      pcLinkToFile
+- Non-pure enum values should use camelCase whereas pure enum values should use
+  PascalCase.
+
+  .. code-block:: nim
+    type PathComponent {.pure.} = enum
+      Dir
+      LinkToDir
+      File
+      LinkToFile
+- In the age of HTTP, HTML, FTP, TCP, IP, UTF, WWW it is foolish to pretend
+  these are somewhat special words requiring all uppercase. Instead tread them as what they are: Real words. So it's ``parseUrl`` rather than ``parseURL``, ``checkHttpHeader`` instead of ``checkHTTPHeader`` etc.
+
+
+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 readability.
+
+- 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.
+
+- For new types, it is usually recommended to have both 'ref' and 'object'
+  versions of the type available for others to use. By making both variants
+  available for use, the type may be allocated both on the stack and the heap.
+
+
+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.
+
+  .. code-block:: nim
+    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.
+
+  .. code-block:: nim
+    type
+      EventCallback = proc (
+        timeRecieved: Time
+        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).
+
+  .. code-block:: nim
+    proc lotsOfArguments(argOne: string, argTwo: int, argThree:float
+                         argFour: proc(), argFive: bool): int
+                        {.heyLookALongPragma.} =
+- 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.
+
+  .. code-block:: nim
+    # 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[Overlapped](ol),
+      cast[OverlappedCompletionRoutine](nil)
+    )
+
+    # Multiple arguments on new lines, aligned to the opening parenthesis
+    # Best suited for 'simple' procedure calls
+    startProcess(nimExecutable, currentDirectory, compilerArguments
+                 environment, processOptions)
diff --git a/doc/nimdoc.css b/doc/nimdoc.css
index e3bab07de..a002b6be1 100644
--- a/doc/nimdoc.css
+++ b/doc/nimdoc.css
@@ -1,4 +1,9 @@
 /*

+NOTE - THIS IS PROBABLY NOT THE CSS FILE YOU WANT

+The CSS text used by Nim's documentation tools (such as 'koch web',

+'rst2html', etc) is contained in 'config\nimdoc.cfg'

+*/

+/*

 :Author: David Goodger

 :Contact: goodger@python.org

 :Date: $Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006) $

diff --git a/doc/tut1.txt b/doc/tut1.txt
index 34684a850..23d8a9b57 100644
--- a/doc/tut1.txt
+++ b/doc/tut1.txt
@@ -20,7 +20,8 @@ This document is a tutorial for the programming language *Nim*.
 This tutorial assumes that you are familiar with basic programming concepts
 like variables, types or statements but is kept very basic. The `manual
 <manual.html>`_ contains many more examples of the advanced language features.
-
+All code examples in this tutorial, as well as the ones found in the rest of
+Nim's documentation, follow the `Nim style guide <nep1.html>`.
 
 
 The first program
diff --git a/web/documentation.txt b/web/documentation.txt
index 67f8b4070..afb25d1d1 100644
--- a/web/documentation.txt
+++ b/web/documentation.txt
@@ -14,6 +14,9 @@ Nim's Documentation
     - | `Language Manual <docs/manual.html>`_
       | The Nim manual is a draft that will evolve into a proper specification.
 
+    - | `Nim Style Guide <nep1.html>`_
+      | The stylistic conventions that Nim's official projects adhere to.
+
     - | `Compiler User Guide <docs/nimc.html>`_
       | The user guide lists command line arguments, special features of the
         compiler, etc.
diff --git a/web/website.ini b/web/website.ini
index fb98d639a..95f0f5b57 100644
--- a/web/website.ini
+++ b/web/website.ini
@@ -31,7 +31,7 @@ file: ticker.txt
 [Documentation]
 doc: "endb;intern;apis;lib;manual.txt;tut1;tut2;nimc;overview;filters"
 doc: "tools;niminst;nimgrep;gc;estp;idetools;docgen;koch;backends.txt"
-doc: "nimfix.txt;nimsuggest.txt"
+doc: "nimfix.txt;nimsuggest.txt;nep1.txt"
 pdf: "manual.txt;lib;tut1;tut2;nimc;niminst;gc"
 srcdoc2: "system.nim"
 srcdoc2: "core/macros;pure/marshal;core/typeinfo;core/unsigned"