From be586469e39cc904a43cf81493ec5dcd107b5514 Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 02:28:59 -0700 Subject: [PATCH 01/10] Detab dstyle.dd and remove trailing whitespace. --- dstyle.dd | 168 +++++++++++++++++++++++++++--------------------------- 1 file changed, 84 insertions(+), 84 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index d5fedb284a..0c3fe0af6c 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -3,49 +3,49 @@ Ddoc $(D_S The D Style, $(P - $(I The D Style) is a set of style conventions for writing - D programs. The D Style is not enforced by the compiler, it is - purely cosmetic and a matter of choice. Adhering to the D Style, - however, will make it easier for others to work with your - code and easier for you to work with others' code. - The D Style can form the starting point for a project - style guide customized for your project team. + $(I The D Style) is a set of style conventions for writing + D programs. The D Style is not enforced by the compiler, it is + purely cosmetic and a matter of choice. Adhering to the D Style, + however, will make it easier for others to work with your + code and easier for you to work with others' code. + The D Style can form the starting point for a project + style guide customized for your project team. ) $(P - Submissions to Phobos and other official D source code will - follow these guidelines. + Submissions to Phobos and other official D source code will + follow these guidelines. )

White Space

$(UL - $(LI One statement per line.) + $(LI One statement per line.) - $(LI Use spaces instead of hardware tabs.) + $(LI Use spaces instead of hardware tabs.) - $(LI Each indentation level will be four columns.) + $(LI Each indentation level will be four columns.) - $(LI Operators are separated by single spaces from their operands.) + $(LI Operators are separated by single spaces from their operands.) - $(LI Two blank lines separating function bodies.) + $(LI Two blank lines separating function bodies.) - $(LI One blank line separating variable declarations from statements - in function bodies.) + $(LI One blank line separating variable declarations from statements + in function bodies.) )

Comments

$(UL - $(LI Use // comments to document a single line: + $(LI Use // comments to document a single line: ------------------------------- -statement; // comment -statement; // comment +statement; // comment +statement; // comment ------------------------------- - ) + ) - $(LI Use block comments to document a multiple line block of - statements: + $(LI Use block comments to document a multiple line block of + statements: ------------------------------- /* comment * comment @@ -53,10 +53,10 @@ statement; // comment statement; statement; ------------------------------- - ) + ) - $(LI Use $(CODE version (none)) to $(SINGLEQUOTE comment out) a piece of trial code - that is syntactically valid: + $(LI Use $(CODE version (none)) to $(SINGLEQUOTE comment out) a piece of trial code + that is syntactically valid: ------------------------------- version (none) { @@ -68,7 +68,7 @@ statement; // comment } ------------------------------- - It can be turned on with $(CODE version(all)): + It can be turned on with $(CODE version(all)): ------------------------------- version (all) @@ -81,9 +81,9 @@ statement; // comment } ------------------------------- - ) + ) - $(LI Use nesting comments to $(SINGLEQUOTE comment out) a piece of syntactically invalid code: + $(LI Use nesting comments to $(SINGLEQUOTE comment out) a piece of syntactically invalid code: ------------------------------- /+++++ /* comment @@ -93,73 +93,73 @@ statement; // comment statement; +++++/ ------------------------------- - ) + ) )

Naming Conventions

$(DL $(DT General) -
Names formed by joining multiple words should have each word - other than the first capitalized. - Names shall not begin with an underscore $(SINGLEQUOTE _) unless they are private member variables. +
Names formed by joining multiple words should have each word + other than the first capitalized. + Names shall not begin with an underscore $(SINGLEQUOTE _) unless they are private member variables. ------------------------------- int myFunc(); ------------------------------- $(DT Module) - $(DD Module and package names are all lower case, and only contain - the characters [a..z][0..9][_]. This avoids problems dealing - with case insensitive file systems.) + $(DD Module and package names are all lower case, and only contain + the characters [a..z][0..9][_]. This avoids problems dealing + with case insensitive file systems.) $(DT C Modules) - $(DD Modules that are interfaces to C functions go into the "c" - package, for example: + $(DD Modules that are interfaces to C functions go into the "c" + package, for example: ------------------------------- import std.c.stdio; ------------------------------- - Module names should be all lower case. - ) + Module names should be all lower case. + ) $(DT Class, Struct, Union, Enum, Template names) - $(DD are capitalized. + $(DD are capitalized. ------------------------------- class Foo; class FooAndBar; ------------------------------- - ) - $(DD An exception is that eponymous templates that return a value instead of a type should not be - capitalized, as they are conceptually more similar to functions. + ) + $(DD An exception is that eponymous templates that return a value instead of a type should not be + capitalized, as they are conceptually more similar to functions. -------------------------- -template GetSomeType(T) {} -template isSomeType(T) {} -------------------------- - ) +------------------------- +template GetSomeType(T) {} +template isSomeType(T) {} +------------------------- + ) $(DT Function names) - $(DD Function names are not capitalized. + $(DD Function names are not capitalized. ------------------------------- int done(); int doneProcessing(); ------------------------------- - ) + ) $(V1 $(DT Const names) - $(DD Are in all caps.) + $(DD Are in all caps.) ) $(DT Enum member names) - $(DD Are in lowerCamelCase.) + $(DD Are in lowerCamelCase.) )

Meaningless Type Aliases

- $(P Things like:) + $(P Things like:) ------------------------------- alias void VOID; @@ -167,65 +167,65 @@ alias int INT; alias int* pint; ------------------------------- - $(P should be avoided.) + $(P should be avoided.)

Declaration Style

- $(P Since the declarations are left-associative, left justify them:) + $(P Since the declarations are left-associative, left justify them:) ------------------------------- -int[] x, y; // makes it clear that x and y are the same type -int** p, q; // makes it clear that p and q are the same type +int[] x, y; // makes it clear that x and y are the same type +int** p, q; // makes it clear that p and q are the same type ------------------------------- - $(P to emphasize their relationship. Do not use the C style:) + $(P to emphasize their relationship. Do not use the C style:) ------------------------------- -int []x, y; // confusing since y is also an int[] -int **p, q; // confusing since q is also an int** +int []x, y; // confusing since y is also an int[] +int **p, q; // confusing since q is also an int** -------------------------------

Operator Overloading

- $(P Operator overloading is a powerful tool to extend the basic - types supported by the language. But being powerful, it has - great potential for creating obfuscated code. In particular, - the existing D operators have conventional meanings, such - as $(SINGLEQUOTE +) means $(SINGLEQUOTE add) and $(SINGLEQUOTE <<) - means $(SINGLEQUOTE shift left). - Overloading operator $(SINGLEQUOTE +) with a meaning different from $(SINGLEQUOTE add) - is arbitrarily confusing and should be avoided. - ) + $(P Operator overloading is a powerful tool to extend the basic + types supported by the language. But being powerful, it has + great potential for creating obfuscated code. In particular, + the existing D operators have conventional meanings, such + as $(SINGLEQUOTE +) means $(SINGLEQUOTE add) and $(SINGLEQUOTE <<) + means $(SINGLEQUOTE shift left). + Overloading operator $(SINGLEQUOTE +) with a meaning different from $(SINGLEQUOTE add) + is arbitrarily confusing and should be avoided. + )

Hungarian Notation

- $(P Using hungarian notation to denote the type of a variable - is a bad idea. - However, using notation to denote the purpose of a variable - (that cannot be expressed by its type) is often a good - practice.) + $(P Using hungarian notation to denote the type of a variable + is a bad idea. + However, using notation to denote the purpose of a variable + (that cannot be expressed by its type) is often a good + practice.)

Documentation

$(P - All public declarations will be documented in - $(LINK2 ddoc.html, Ddoc) format. + All public declarations will be documented in + $(LINK2 ddoc.html, Ddoc) format. )

Unit Tests

$(P - As much as practical, all functions will be exercised - by unit tests using unittest blocks immediately following - the function to be tested. - Every path of code should be executed at least once, - verified by the $(LINK2 code_coverage.html, code coverage analyzer). + As much as practical, all functions will be exercised + by unit tests using unittest blocks immediately following + the function to be tested. + Every path of code should be executed at least once, + verified by the $(LINK2 code_coverage.html, code coverage analyzer). ) ) Macros: - TITLE=The D Style - WIKI=DStyle - CATEGORY_APPENDICES=$0 + TITLE=The D Style + WIKI=DStyle + CATEGORY_APPENDICES=$0 From 58a0960bad91fe46a836deb1f605b94d23605468 Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 02:29:20 -0700 Subject: [PATCH 02/10] Removed overly restrictive whitespace requirements. Phobos doesn't consistently follow them anyway. --- dstyle.dd | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index 0c3fe0af6c..f3e306568b 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -17,7 +17,7 @@ $(P follow these guidelines. ) -

White Space

+

Whitespace

$(UL $(LI One statement per line.) @@ -25,13 +25,6 @@ $(UL $(LI Use spaces instead of hardware tabs.) $(LI Each indentation level will be four columns.) - - $(LI Operators are separated by single spaces from their operands.) - - $(LI Two blank lines separating function bodies.) - - $(LI One blank line separating variable declarations from statements - in function bodies.) )

Comments

From c5d0f71007b3d87c529eb21a4c7c4ffa996bd87d Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 02:31:10 -0700 Subject: [PATCH 03/10] Removed Comments section from style guide. I don't see any reason to require a particular commenting style in any given situation, and Phobos doesn't stick to those requirements anyway. --- dstyle.dd | 62 ------------------------------------------------------- 1 file changed, 62 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index f3e306568b..fa017ea050 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -27,68 +27,6 @@ $(UL $(LI Each indentation level will be four columns.) ) -

Comments

- -$(UL - $(LI Use // comments to document a single line: -------------------------------- -statement; // comment -statement; // comment -------------------------------- - ) - - $(LI Use block comments to document a multiple line block of - statements: -------------------------------- -/* comment - * comment - */ - statement; - statement; -------------------------------- - ) - - $(LI Use $(CODE version (none)) to $(SINGLEQUOTE comment out) a piece of trial code - that is syntactically valid: -------------------------------- - version (none) - { - /* comment - * comment - */ - statement; - statement; - } -------------------------------- - - It can be turned on with $(CODE version(all)): - -------------------------------- - version (all) - { - /* comment - * comment - */ - statement; - statement; - } -------------------------------- - - ) - - $(LI Use nesting comments to $(SINGLEQUOTE comment out) a piece of syntactically invalid code: -------------------------------- -/+++++ - /* comment - * comment - */ - { statement; - statement; - +++++/ -------------------------------- - ) -) -

Naming Conventions

$(DL From 3915d63e62a077020362e1ce780e7de3a00c344e Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 03:26:06 -0700 Subject: [PATCH 04/10] Various adjustments and clarifications to the naming conventions. They haven't really been changed so much as cleaned up, however. Phobos is not entirely consistent with them, but they're what we've generally agreed upon, and Phobos should be changed to be more consistent with them where appropriate. --- dstyle.dd | 64 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 23 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index fa017ea050..1efed832db 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -31,38 +31,43 @@ $(UL $(DL $(DT General) -
Names formed by joining multiple words should have each word - other than the first capitalized. - Names shall not begin with an underscore $(SINGLEQUOTE _) unless they are private member variables. +
Names should be camel-cased. So, names formed by joining multiple words + have each word other than the first capitalized. Also, names do not begin + with an underscore $(SINGLEQUOTE _) unless they are private member + variables. ------------------------------- int myFunc(); ------------------------------- $(DT Module) - $(DD Module and package names are all lower case, and only contain - the characters [a..z][0..9][_]. This avoids problems dealing - with case insensitive file systems.) + $(DD Module and package names should be all lowercase, and only contain + the characters [a..z][0..9][_]. This avoids problems dealing with case + insensitive file systems. +------------------------------- +import std.algorithm; +------------------------------- + ) $(DT C Modules) - $(DD Modules that are interfaces to C functions go into the "c" - package, for example: + $(DD Modules that are interfaces to C functions go into the "c" package. ------------------------------- import std.c.stdio; ------------------------------- - Module names should be all lower case. ) - $(DT Class, Struct, Union, Enum, Template names) - $(DD are capitalized. + $(DT Classs, Structs, Unions, Enums, Templates) + $(DD The names of user-defined types should be pascal-cased, which is the + same as camel-cased except that the first letter is uppercase. ------------------------------- class Foo; -class FooAndBar; +struct FooAndBar; ------------------------------- ) - $(DD An exception is that eponymous templates that return a value instead of a type should not be - capitalized, as they are conceptually more similar to functions. + $(DD An exception is that eponymous templates that return a value instead of + a type should not be capitalized, as they are conceptually more similar to + functions. ------------------------- template GetSomeType(T) {} @@ -70,8 +75,8 @@ template isSomeType(T) {} ------------------------- ) - $(DT Function names) - $(DD Function names are not capitalized. + $(DT Functions) + $(DD Function names should be camel-cased, so their first letter is lowercase.) ------------------------------- int done(); @@ -79,14 +84,27 @@ int doneProcessing(); ------------------------------- ) -$(V1 - $(DT Const names) - $(DD Are in all caps.) -) - $(DT Enum member names) - $(DD Are in lowerCamelCase.) + $(DT Constants) + $(DD The names of constants should generally be camel-cased just like normal + variables, though shorter constants (e.g. PI) can be all uppercase. In + general however, constants should $(I not) be in all uppercase. They aren't + C macros and don't need to worry about the C pre-processor. -) +------------------------------- +enum secondsPerMinute = 60; +immutable hexDigits = "0123456789ABCDEF"; +------------------------------- + ) + + $(DT Enum members) + $(DD The members of enums should be camel-cased, so their first letter is + lowercase. + +------------------------------- +Enum Direction { bwd, fwd, both } +Enum OpenRight { no, yes } +------------------------------- + )

Meaningless Type Aliases

From 4c64092c61e4009afd42e218d28996a0ceeccb46 Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 03:31:42 -0700 Subject: [PATCH 05/10] Added a note on property functions to style guide. --- dstyle.dd | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/dstyle.dd b/dstyle.dd index 1efed832db..90984881f5 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -154,6 +154,13 @@ int **p, q; // confusing since q is also an int** (that cannot be expressed by its type) is often a good practice.) +

Properties

+ + $(P Functions should be property functions whenever appropriate. In + particular, getters and setters should generally be avoided in favor of + property functions. And in general, whereas functions should be verbs, + properties should be nouns, just like if they were member variables.) +

Documentation

$(P From f632d82dbae98e84b6fe5c5d67f1fbec70a0a904 Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 03:50:46 -0700 Subject: [PATCH 06/10] Added additional requirements specific to Phobos to style guide. --- dstyle.dd | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/dstyle.dd b/dstyle.dd index 90984881f5..01e13cd2ce 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -4,7 +4,7 @@ $(D_S The D Style, $(P $(I The D Style) is a set of style conventions for writing - D programs. The D Style is not enforced by the compiler, it is + D programs. The D Style is not enforced by the compiler. It is purely cosmetic and a matter of choice. Adhering to the D Style, however, will make it easier for others to work with your code and easier for you to work with others' code. @@ -178,6 +178,46 @@ $(P verified by the $(LINK2 code_coverage.html, code coverage analyzer). ) +

Additional Requirements for Phobos

+ +$(P + This guide in general does not try to recommend or require that you follow + any particular formatting guidelines. The small section on whitespace at the + top contains the only formatting guidelines. However, for Phobos and other + official D source code, there are two additional requirements: + ) + +$(UL + $(LI Braces should be on their own line. There are a few exceptions to this + (such as when declaring lambda functions), but with any normal function + block or type definition, the braces should be on their own line.) + +------------------------------- +void func(int param) +{ + if(param < 0) + { + ... + } + else + { + ... + } +} +------------------------------- + + $(LI Lines have a soft limit of 80 characters and a hard limit of 120 + characters. This means that most lines of code should be no longer than 80 + characters long, but they can exceed 80 characters when appropriate. + However, they can never exceed 120 characters.) + ) + +$(P + We are not necessarily recommending that you follow these two rules in your + own source code. They're both likely to be controversial in any discussion + on coding standards. However, they are required in submissions to Phobos and + other official D source code. + ) ) Macros: From a345621f2a33718ba4a1bb0c22fa933ad4ef52af Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 04:01:33 -0700 Subject: [PATCH 07/10] Some additional tweaks to the style guide. --- dstyle.dd | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index 01e13cd2ce..bf80e46594 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -32,8 +32,8 @@ $(UL $(DL $(DT General)
Names should be camel-cased. So, names formed by joining multiple words - have each word other than the first capitalized. Also, names do not begin - with an underscore $(SINGLEQUOTE _) unless they are private member + have each word other than the first word capitalized. Also, names do not + begin with an underscore $(SINGLEQUOTE _) unless they are private member variables. ------------------------------- @@ -42,7 +42,7 @@ int myFunc(); $(DT Module) $(DD Module and package names should be all lowercase, and only contain - the characters [a..z][0..9][_]. This avoids problems dealing with case + the characters [a..z][0..9][_]. This avoids problems when dealing with case insensitive file systems. ------------------------------- import std.algorithm; @@ -50,7 +50,8 @@ import std.algorithm; ) $(DT C Modules) - $(DD Modules that are interfaces to C functions go into the "c" package. + $(DD Modules that are interfaces to C functions go into the "c" package and + are all lowercase just like any other module. ------------------------------- import std.c.stdio; ------------------------------- @@ -164,8 +165,13 @@ int **p, q; // confusing since q is also an int**

Documentation

$(P - All public declarations will be documented in - $(LINK2 ddoc.html, Ddoc) format. + All public declarations will be documented in $(LINK2 ddoc.html, Ddoc) + format. In addition, in Phobos and other official D source, when you need + to have version block specifically for Ddoc, use version(StdDdoc) instead + of version(D_Ddoc). This is so that users can generate documentation with + their normal builds if they want to rather than having to have a separate + build for their documentation. + )

Unit Tests

From 259cfde38d3eebc9956210104f4f13f5252168c7 Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 16 Jul 2011 17:50:13 -0700 Subject: [PATCH 08/10] Fixed typo. --- dstyle.dd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dstyle.dd b/dstyle.dd index bf80e46594..207f0f8c22 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -57,7 +57,7 @@ import std.c.stdio; ------------------------------- ) - $(DT Classs, Structs, Unions, Enums, Templates) + $(DT Classes, Structs, Unions, Enums, Templates) $(DD The names of user-defined types should be pascal-cased, which is the same as camel-cased except that the first letter is uppercase. From 7345bea924e1454f9fce312bb5badb0d7f84168b Mon Sep 17 00:00:00 2001 From: jmdavis Date: Thu, 21 Jul 2011 00:09:09 -0700 Subject: [PATCH 09/10] Removed section on C modules. --- dstyle.dd | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index 207f0f8c22..dbf7c3911f 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -40,7 +40,7 @@ $(DL int myFunc(); ------------------------------- - $(DT Module) + $(DT Modules) $(DD Module and package names should be all lowercase, and only contain the characters [a..z][0..9][_]. This avoids problems when dealing with case insensitive file systems. @@ -49,14 +49,6 @@ import std.algorithm; ------------------------------- ) - $(DT C Modules) - $(DD Modules that are interfaces to C functions go into the "c" package and - are all lowercase just like any other module. -------------------------------- -import std.c.stdio; -------------------------------- - ) - $(DT Classes, Structs, Unions, Enums, Templates) $(DD The names of user-defined types should be pascal-cased, which is the same as camel-cased except that the first letter is uppercase. From f9652ccd6da3da1c736383d462e9a6d1cb936fb9 Mon Sep 17 00:00:00 2001 From: jmdavis Date: Sat, 27 Aug 2011 03:27:16 -0700 Subject: [PATCH 10/10] Removed some uses of you per review suggestion. --- dstyle.dd | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/dstyle.dd b/dstyle.dd index dbf7c3911f..27214b0377 100644 --- a/dstyle.dd +++ b/dstyle.dd @@ -158,8 +158,8 @@ int **p, q; // confusing since q is also an int** $(P All public declarations will be documented in $(LINK2 ddoc.html, Ddoc) - format. In addition, in Phobos and other official D source, when you need - to have version block specifically for Ddoc, use version(StdDdoc) instead + format. In addition, in Phobos and other official D source, when a version + block specifically for Ddoc is needed, use version(StdDdoc) instead of version(D_Ddoc). This is so that users can generate documentation with their normal builds if they want to rather than having to have a separate build for their documentation. @@ -179,10 +179,11 @@ $(P

Additional Requirements for Phobos

$(P - This guide in general does not try to recommend or require that you follow - any particular formatting guidelines. The small section on whitespace at the - top contains the only formatting guidelines. However, for Phobos and other - official D source code, there are two additional requirements: + In general, this guide does not try to recommend or require that code + conform to any particular formatting guidelines. The small section on + whitespace at the top contains its only formatting guidelines. However, for + Phobos and other official D source code, there are two additional + requirements: ) $(UL @@ -211,10 +212,10 @@ void func(int param) ) $(P - We are not necessarily recommending that you follow these two rules in your - own source code. They're both likely to be controversial in any discussion - on coding standards. However, they are required in submissions to Phobos and - other official D source code. + We are not necessarily recommending that all code follow these two rules. + They're both likely to be controversial in any discussion on coding + standards. However, they are required in submissions to Phobos and other + official D source code. ) )