diff --git a/NEP-1-:-Style-Guide-for-Nimrod-Code.md b/NEP-1-:-Style-Guide-for-Nimrod-Code.md index 9675c4d..d0c42b9 100644 --- a/NEP-1-:-Style-Guide-for-Nimrod-Code.md +++ b/NEP-1-:-Style-Guide-for-Nimrod-Code.md @@ -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. +
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 + ``` +
+ +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 ``` +
-- 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 + ``` +
+ +- Exception and Error types should have the "Error" suffix. + ```nimrod + type unluckyError = object of E_Base + ``` +
+ +- 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 ``` +
-- 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. +
+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 ``` +
- 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 ) ``` +
- 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 ``` +
- 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 ``` \ No newline at end of file