Skip to content

Proposed updates to the D style guide #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 10 commits into from
Closed

Proposed updates to the D style guide #16

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
be58646
Detab dstyle.dd and remove trailing whitespace.
jmdavis Jul 16, 2011
58a0960
Removed overly restrictive whitespace requirements.
jmdavis Jul 16, 2011
c5d0f71
Removed Comments section from style guide.
jmdavis Jul 16, 2011
3915d63
Various adjustments and clarifications to the naming conventions.
jmdavis Jul 16, 2011
4c64092
Added a note on property functions to style guide.
jmdavis Jul 16, 2011
f632d82
Added additional requirements specific to Phobos to style guide.
jmdavis Jul 16, 2011
a345621
Some additional tweaks to the style guide.
jmdavis Jul 16, 2011
259cfde
Fixed typo.
jmdavis Jul 17, 2011
7345bea
Removed section on C modules.
jmdavis Jul 21, 2011
f9652cc
Removed some uses of you per review suggestion.
jmdavis Aug 27, 2011
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
293 changes: 144 additions & 149 deletions dstyle.dd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,229 +3,224 @@ 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.
)

<h3>White Space</h3>
<h3>Whitespace</h3>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

http://en.wikipedia.org/wiki/Whitespace_character#Definition_and_ambiguity

Personally I've always preferred "white space": I can't stand when words are randomly concatenated...

I don't have any strong preference, though. Just saying that it was correct before, either way.


$(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 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.)
)

<h3>Comments</h3>

$(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;
+++++/
-------------------------------
)
$(LI Each indentation level will be four columns.)
)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why remove this? I think it's an incredibly important rule. Random piece of C code from Libav:

av_malloc(sizeof(AVFilterFormats**)*(a->refcount+b->refcount));

This kind of stuff is completely unreadable.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because we're trying not to specify much in the way of how code is formatted. The guide is more about how things should be named than how they should be formatted. Everyone has different formatting styles, and we'll be bikeshedding to death if we try to settle on one (and we'll probably all endu being unhappy with it in the end anyway). So, we're keeping the number of formatting rules to an absolute minimum.

<h3>Naming Conventions</h3>

$(DL
$(DT General)
<dd>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.
<dd>Names should be camel-cased. So, names formed by joining multiple words
have each word other than the first word 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.)

$(DT C Modules)
$(DD Modules that are interfaces to C functions go into the "c"
package, for example:
$(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.
-------------------------------
import std.c.stdio;
import std.algorithm;
-------------------------------
Module names should be all lower case.
)
)

$(DT Class, Struct, Union, Enum, Template names)
$(DD are capitalized.
$(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.

-------------------------------
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) {}
template isSomeType(T) {}
-------------------------
)
-------------------------
template GetSomeType(T) {}
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();
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.

-------------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why remove this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because I see no reason to have it. We don't follow it in Phobos, and I don't see much reason to require that comments be formatted in a particular way. In general, the Phobos devs have indicated that they don't want to be required to format code in a particular way, and this seems like an unnecessary formatting requirement.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On 8/10/2011 1:20 AM, jmdavis wrote:

Because I see no reason to have it. We don't follow it in Phobos, and I don't see much reason to require that comments be formatted in a particular way. In general, the Phobos devs have indicated that they don't want to be required to format code in a particular way, and this seems like an unnecessary formatting requirement.

Since there are several ways of commenting out code, I think that guidance and a
rationale for that guidance is in order.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I honestly don't see why it matters. Perhaps we should have a more standard way of doing it and be more consistent about it in Phobos, but you shouldn't generally be checking in commented out code anyway. It should be a relatively rare occurence. Certainly, I don't think that there's been all that much consistency in commenting out code in Phobos, and when it has been done, it hasn't generally been done with version(none) as the guide suggested doing. Most developers just comment it out, and I don't see why it really matters whether // or /* */ or /+ +/ is used for that (with the possible exception that it's better not to use /* */, since it doesn't nest).

So, maybe we should be more consistent in how we comment out code, but the general consensus has been to minimize the requirements in the style guide which don't affect the API. And not only does this not affect the API, it's about something which shouldn't even be in the code long term.

Enum Direction { bwd, fwd, both }
Enum OpenRight { no, yes }
-------------------------------
)

<h3>Meaningless Type Aliases</h3>

$(P Things like:)
$(P Things like:)

-------------------------------
alias void VOID;
alias int INT;
alias int* pint;
-------------------------------

$(P should be avoided.)
$(P should be avoided.)

<h3>Declaration Style</h3>

$(P Since the declarations are left-associative, left justify them:)
$(P Since the declarations are left-associative, left justify them:)

-------------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remember that the D1 style guide is also generated from this. Hence, D1 stuff should be in $(V1 ...) and D2 stuff $(V2 ...)

The above is D1 stuff.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any stuff on D1 on d-programming-language.org? D1 Home just redirects to the stuff on www.digitalmars.com. It was my understanding that d-programming-language.org was for D2-only.

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**
-------------------------------

<h3>Operator Overloading</h3>

$(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 &lt;&lt;)
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 &lt;&lt;)
means $(SINGLEQUOTE shift left).
Overloading operator $(SINGLEQUOTE +) with a meaning different from $(SINGLEQUOTE add)
is arbitrarily confusing and should be avoided.
)

<h3>Hungarian Notation</h3>

$(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.)

<h3>Properties</h3>

$(P Functions should be property functions whenever appropriate. In
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably worth mentioning that, in general, anything that performs mutation should not be a "getter property" with the exception being lazy loading.

I hate .reverse and .sort.

particular, getters and setters should generally be avoided in favor of
property functions. And in general, whereas functions should be verbs,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do not delete D1 stuff.

properties should be nouns, just like if they were member variables.)

<h3>Documentation</h3>

$(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 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.

)

<h3>Unit Tests</h3>

$(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).
)

<h2>Additional Requirements for Phobos</h2>

$(P
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
$(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 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.
)
)

Macros:
TITLE=The D Style
WIKI=DStyle
CATEGORY_APPENDICES=$0
TITLE=The D Style
WIKI=DStyle
CATEGORY_APPENDICES=$0