121 lines
4.2 KiB
Markdown
121 lines
4.2 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 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. |