Skip to content

Enable section links to the DStyle #1813

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

Merged
dlang-bot merged 1 commit into from
Jul 10, 2017
Merged

Enable section links to the DStyle #1813

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
59 changes: 30 additions & 29 deletions dstyle.dd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ $(P
follow these guidelines.
)

$(H3 Whitespace)
$(H3 $(LNAME2 whitespace, Whitespace))

$(UL
$(LI One statement per line.)
Expand All @@ -29,10 +29,10 @@ $(UL
$(LI Each indentation level will be four columns.)
)

$(H3 Naming Conventions)
$(H3 $(LNAME2 naming_conventions, Naming Conventions))

$(DL
$(DT General)
$(DT $(LNAME2 naming_general, General))
$(DD Unless listed otherwise below, names should be camelCased (this
includes $(I all) variables). So, names formed by joining multiple
words have each word other than the first word capitalized. Also, names
Expand All @@ -45,7 +45,7 @@ string myLocalVar;
-------------------------------
)

$(DT Modules)
$(DT $(LNAME2 naming_modules, 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.
Expand All @@ -56,7 +56,7 @@ import std.algorithm;



$(DT Classes, Interfaces, Structs, Unions, Enums, Non-Eponymous Templates)
$(DT $(LNAME2 naming_classes, Classes, Interfaces, Structs, Unions, Enums, Non-Eponymous Templates))
$(DD The names of user-defined types should be PascalCased, which is the
same as camelCased except that the first letter is uppercase.

Expand All @@ -66,7 +66,7 @@ struct FooAndBar;
-------------------------------
)

$(DT Eponymous Templates)
$(DT $(LNAME2 naming_eponymous_templates, Eponymous Templates))

$(DD Templates which have the same name as a symbol within that template
(and instantiations of that template are therefore replaced with that
Expand All @@ -82,7 +82,7 @@ template map(fun...) { auto map(Range r) { ... } }
-------------------------
)

$(DT Functions)
$(DT $(LNAME2 naming_functions, Functions))
$(DD Function names should be camelCased, so their first letter is lowercase.
This includes properties and member functions.

Expand All @@ -92,7 +92,7 @@ int doneProcessing();
-------------------------------
)

$(DT Constants)
$(DT $(LNAME2 naming_constants, Constants))
$(DD The names of constants should be camelCased just like normal variables.

-------------------------------
Expand All @@ -101,7 +101,7 @@ immutable hexDigits = "0123456789ABCDEF";
-------------------------------
)

$(DT Enum members)
$(DT $(LNAME2 naming_enum_members, Enum members))
$(DD The members of enums should be camelCased, so their first letter is
lowercase.

Expand All @@ -111,7 +111,7 @@ enum OpenRight { no, yes }
-------------------------------
)

$(DT Keywords)
$(DT $(LNAME2 naming_keywords, Keywords))
$(DD If a name would conflict with a keyword, and it is desirable to use the
keyword rather than pick a different name, a single underscore
$(SINGLEQUOTE _) should be appended to it. Names should not be
Expand All @@ -122,7 +122,7 @@ enum Attribute { nothrow_, pure_, safe }
-------------------------------
)

$(DT Acronyms)
$(DT $(LNAME2 naming_acronyms, Acronyms))
$(DD When acronyms are used in symbol names, all letters in the acronym
should have the same case. So, if the first letter in the acronym
is lowercase, then all of the letters in the acronym are lowercase, and
Expand All @@ -138,7 +138,7 @@ ubyte asciiChar;

)

$(H3 Type Aliases)
$(H3 $(LNAME2 type_aliases, Type Aliases))

$(P The D programming languages offers two functionally equivalent syntaxes for type aliases, but ...)

Expand Down Expand Up @@ -181,7 +181,7 @@ alias pint = int*;

$(P ... should be avoided.)

$(H3 Declaration Style)
$(H3 $(LNAME2 declaration_style, Declaration Style))

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

Expand All @@ -197,7 +197,7 @@ int []x, y; // confusing since y is also an int[]
int **p, q; // confusing since q is also an int**
-------------------------------

$(H3 Operator Overloading)
$(H3 $(LNAME2 operator_overloading, Operator Overloading))

$(P Operator overloading is a powerful tool to extend the basic
types supported by the language. But being powerful, it has
Expand All @@ -209,31 +209,31 @@ $(H3 Operator Overloading)
is arbitrarily confusing and should be avoided.
)

$(H3 Hungarian Notation)
$(H3 $(LNAME2 hungarian_notation, 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.)

$(H3 Properties)
$(H3 $(LNAME2 properties, 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.
Getter properties should $(I not) alter state.)

$(H3 Documentation)
$(H3 $(LNAME2 documentation, Documentation))

$(P
All public declarations will be documented in
$(LINK2 spec/ddoc.html, Ddoc) format and should have at least `Params` and
`Returns` sections.
)

$(H3 Unit Tests)
$(H3 $(LNAME2 unittest, Unit Tests))

$(P
As much as practical, all functions will be exercised
Expand All @@ -243,7 +243,7 @@ $(P
verified by the $(LINK2 code_coverage.html, code coverage analyzer).
)

$(H2 Additional Requirements for Phobos)
$(H2 $(LNAME2 phobos, Additional Requirements for Phobos))

$(P
In general, this guide does not try to recommend or require that code
Expand All @@ -252,7 +252,7 @@ $(P
Phobos and other official D source code, there are additional requirements:
)

$(H4 Brackets)
$(H4 $(LNAME2 phobos_brackets, Brackets))
$(P 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.)
Expand All @@ -275,12 +275,12 @@ void func(int param)
(a == b) ? "foo" : "bar"; // NO
a == b ? "foo" : "bar"; // OK
-------------------------------
$(H4 Line length)
$(H4 $(LNAME2 phobos_line_length, Line length))
$(P 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 that they $(I can) exceed 80 characters when
appropriate. However, they can $(I never) exceed 120 characters.)
$(LISTSECTION Whitespace,
$(LISTSECTION phobos_whitespace, Whitespace,
$(LI Put a space after `for`, `foreach`, `if`, and `while`: )
-------------------------------
for (…) { … }
Expand Down Expand Up @@ -324,20 +324,20 @@ assert(*d == 42);
callMyFancyFunction("hello world");
-------------------------------
)
$(LISTSECTION Imports,
$(LISTSECTION phobos_imports, Imports,
$(LI Local, selective imports should be preferred over global imports)
$(LI Selective imports should have a space before and after the colon (`:`) like
`import std.range : zip`)
$(LI Imports should be sorted lexicographically.)
)
$(LISTSECTION Return type,
$(LISTSECTION phobos_return_types, Return type,
$(LI The return type should be stated $(I explicitly) wherever possible,
as it makes the documentation and source code easier to read.)
$(LI $(LINK2 https://dlang.org/spec/struct.html#nested, Function-nested) structs
(aka $(LINK2 https://wiki.dlang.org/Voldemort_types, Voldemort types))
should be preferred over public `struct`s.)
)
$(LISTSECTION Attributes,
$(LISTSECTION phobos_attributes, Attributes,
$(LI $(I Non-templated) functions should be annotated with
matching attributes (`@nogc`, `@safe`, `pure`, `nothrow`).)
$(LI $(I Templated) functions should $(B not) be annotated with attributes
Expand All @@ -349,20 +349,20 @@ $(LISTSECTION Attributes,
(e.g. `pure nothrow @nogc @safe unittest { ... }`)
to ensure the existence of attributes on the templated function.)
)
$(LISTSECTION Templates,
$(LISTSECTION phobos_templates, Templates,
$(LI `unittest` blocks should be avoided in templates. They will generate
a new `unittest` for each instance, hence tests should be put
outside of the template.)
)
$(LISTSECTION Declarations,
$(LISTSECTION phobos_declarations, Declarations,
$(LI Constraints on declarations should have the same indentation level as
their declaration:)
-------------------------------
void foo(R)(R r)
if (R == 1)
-------------------------------
)
$(LISTSECTION Class/Struct Field Declarations,
$(LISTSECTION phobos_class_struct_field_declaration, Class/Struct Field Declarations,
$(LI In structs and classes, there should only be one space between the type of
the field and its name. This avoids problems with future changes generating a
larger git diff than necessary.)
Expand Down Expand Up @@ -391,5 +391,6 @@ $(P

Macros:
TITLE=The D Style
LISTSECTION=$(H4 $1) $(UL $+)
LISTSECTION=$(H4 $(LNAME2 $1, $2)) $(UL $(SKIPFIRST $+))
SKIPFIRST=$+