Updated NEP 1 : Style Guide for Nimrod Code (markdown)

This commit is contained in:
Varriount 2014-07-19 19:04:17 -07:00
parent 3a04468b87
commit 81268d3a98
1 changed files with 74 additions and 51 deletions

View File

@ -13,11 +13,48 @@ 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.
<br>
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.
- 2 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 consistant across editors. Unlike spaces, tabstop width varies
across editors, and not all editors provide means of changing this width.
- Use of extra whitespace for alignment in ways other than dictated by the
style guide is discouraged. Manual alignment and re-alignment of code is
tedious, and not all editors have support for auto-alignment of code
sections, plus re-alignment of code blocks causes larger, less distinct
code diffs.
```nimrod
# 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
CalId* = int
LongLong* = int64
LongLongPtr* = ptr LongLong
```
<br>
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 identifer - 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.
General
-------
- Type identifiers should be in CamelCase. All other identifiers should be in
pascalCase.
```nimrod
@ -27,9 +64,28 @@ General
type FooBar = object
```
<br>
- Members of enums should have an identifying prefix, such as an abbreviation
of the enum's name.
- 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 all versions.
```nimrod
type
handle = int64 # Will be used most often
handleRef = ref handle # Will be used less often
```
<br>
- Exception and Error types should have the "Error" suffix.
```nimrod
type unluckyError = object of E_Base
```
<br>
- Unless marked with the `{.pure.}` pragma, members of enums should have an
identifying prefix, such as an abbreviation of the enum's name. Since
non-pure enum members can be referenced without
```nimrod
type PathComponent = enum
pcDir
@ -37,13 +93,10 @@ General
pcFile
pcLinkToFile
```
<br>
- 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.
Coding Conventions
----------------
- 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
@ -53,7 +106,10 @@ General
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.
<br>
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
@ -67,6 +123,7 @@ General
wordyTupleMemberTwo: int
wordyTupleMemberThree: double
```
<br>
- Similarly, any procedure type declarations that are longer than one line
should be formatted in the style of a regular type.
@ -78,15 +135,19 @@ General
event: Event
)
```
<br>
- 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.
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).
```nimrod
proc lotsOfArguments(argOne: string, argTwo: int, argThree:float
argFour: proc(), argFive:bool): int
```
<br>
- Multi-line procedure calls should either have one argument per line
(like multi-line type declarations) or continue on the same
@ -114,41 +175,3 @@ General
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.
Incorrect:
```nimrod
type
WORDBOOL* = int16
CALTYPE* = int
CALID* = int
CCHAR* = char
TCOLORREF* = COLORREF
WINT* = int32
PINTEGER* = ptr int32
PBOOL* = ptr WINBOOL
LONGLONG* = int64
PLONGLONG* = ptr LONGLONG
LPLONGLONG* = ptr LONGLONG
```
Correct:
```nimrod
type
WORDBOOL* = int16
CALTYPE* = int
CALID* = int
CCHAR* = char
TCOLORREF* = COLORREF
WINT* = int32
PINTEGER* = ptr int32
PBOOL* = ptr WINBOOL
LONGLONG* = int64
PLONGLONG* = ptr LONGLONG
LPLONGLONG* = ptr LONGLONG
```