97 lines
3.3 KiB
Markdown
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. |