Updated NEP 1 : Style Guide for Nimrod Code (markdown)
This commit is contained in:
Varriount
parent
3a04468b87
commit
81268d3a98
|
|
@ -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
|
||||
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
|
||||
|
|
@ -113,42 +174,4 @@ General
|
|||
# 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.
|
||||
|
||||
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
|
||||
```
|
||||
Loading…
Reference in New Issue