diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg index e036c3b9a5..57d4cc9881 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 0000000000..e44ec83826 --- /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`_ 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 e3bab07de3..a002b6be1a 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 34684a8502..23d8a9b57e 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 `_ 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 `. The first program diff --git a/web/documentation.txt b/web/documentation.txt index 67f8b4070b..afb25d1d17 100644 --- a/web/documentation.txt +++ b/web/documentation.txt @@ -14,6 +14,9 @@ Nim's Documentation - | `Language Manual `_ | The Nim manual is a draft that will evolve into a proper specification. + - | `Nim Style Guide `_ + | The stylistic conventions that Nim's official projects adhere to. + - | `Compiler User Guide `_ | The user guide lists command line arguments, special features of the compiler, etc. diff --git a/web/website.ini b/web/website.ini index fb98d639aa..95f0f5b57e 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"