nim-wiki/NEP-1.md

97 lines
3.3 KiB
Markdown

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 consistant 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 identifiers should be in
pascalCase.
```
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.
```
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 unneccessary
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 declarding 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.
```
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.
```
type
EventCallback = proc (
timeRecieved: TTime
errorCode: int
event: Event
)
```
- Multi-line procedure declarations/argument lists should continue on the same
column as the preceding brace. This style is different from that of procedure
type declarations in order to prevent confusion between the heading of a
procedure and its body.
```
proc lotsOfArguments(argOne: string, argTwo: int, argThree:float
argFour: proc(), argFive:bool): int
```
- Use of extra whitespace for alignment is generally discouraged. This is not
neccessarily because such a style is bad, but because of the varying support
editors have for auto aligning blocks of code, and the fact that manually
aligning and re-aligning parts of code can be quite time consuming.