A Beginner's Guide to D/Style Guide

From Wikibooks, the open-content textbooks collection

[edit] Be Bold

Don't be afraid to make changes. If something is not worded well, just change it. If only minor changes are needed, just fix them. Don't let anything below this stop you.

If you want to write or edit full pages, however, read on.

[edit] Organization

This book is divided into chapters and subsections. The chapters, generally, refer to general subjects, and their sections refer to specific subjects. The chapters are numbered, but the numbering convention is only used on the tables of content: the numbers should not be assumed to be static.

Each section has its own page (subsections do not), and each chapter has a page which is simply an introduction to the concept, and a table of contents for the chapter. Note that this means that the table of contents will need to be maintained in two locations (the front page and each chapter).

[edit] Naming

The sections in the Table of Contents should be named by the concept they will teach, not the construct. That is, rather than, for example, being named "The if Conditional", a section should be named "Conditions and Branching". When implementing a section, please give it a concept-oriented name; do not keep the name on the TOC if it's not concept-oriented. Titles should be capitalized, but D keywords in titles should not be.

[edit] Development

While the page is being written, use templates to show that it is a stub. If you are still actively writing it, use this template:

{{A Beginner's Guide to D/Stub}}

Otherwise, use either the chapter stub:

{{chapter stub}}

or section stub:

{{sectstub}}

as appropriate.

[edit] Dependencies

No section should depend on concepts taught in later sections. This is hopefully fairly obvious.

It is perfectly acceptable to refer to future concepts, so long as you do not actually depend on them being learned.

[edit] Style

New terminology should be in italics, variable names in 'single quotes', and snippets of code, keywords or symbols in monospace font. Avoid using 1st person (that is, "I", "me", "my" and such) and 2nd person (that is, "you", "your", "etc").

Feel free to use metaphors to describe concepts, just be careful not to take them beyond their limit.

[edit] Code

• Most sections should include one or more example code sections, no matter how trivial.
• This book is on the D language, not Phobos, so please use only din and dout in the examples. Descriptions of Phobos and other popular libraries will be contained in the appendix.
• Try to make each example, where appropriate, a complete application such that it contains a main() function and can compile and run in one step.
• Sections of code in the book must use the following coding convention:

int fun(int a, bool b, float c) // spaces between function parameters
{
    // opening brace goes on its own line
    if (before) // conditionals, loops, etc... have a space before their arguments
    {
        // this brace style in functions, conditionals, and declarations
    }
    else
    {
        class Foo : Bar
        {
        }
    }
 
    // four spaces (no tabs) for indentation and alignment
 
    // empty lines may or may not have spaces
 
    int sample = 2 + 3; // space between operators and their operands
                        // no space before final ';'
    sample++;   // Except that there is no space between unary operator
                // and its operand.
    --sample;
 
    xyzzy(sample, 3.1472); // no space between function call and param list
 
    while (a.very.long.line.is.being.forced && to.wrap || or.look.very.ugly +
           it.will.wrap.at.column - 80)
    {
    }
}
void main()
{
    fun(42, true, 99.94);
}

[edit] Console Input/Output

Example console output should be in bold, monospaced blocks. Wrapping should occur at column 80 as with code examples. Example input should be in bold italics. E.g.:

This is an example of console output. It wraps at column 80. Lorem ipsum dolor 
sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut 
labore et dolore magna aliqua.

Enter user name: example
Enter password: ****

[edit] Attribution

Gregor Richards, who initialized this book and will be overseeing it, is a stickler for attribution. While the wiki does come equipped with a history, Gregor feels that it is important to identify separately the primary contributors. All pages should have attribution (that is, bylines), citing the original author, significant contributors and editors.

There's no strict definition of a "significant contribution", but here are some examples:

• If you've written an entire page, that is of course a significant contribution.
• If you've written an entire subsection on a page, that is significant enough for attribution.
• If you've only changed a few minor grammar or code style mistakes, that is not significant enough for attribution.
• If you've changed a small amount of wording to be less irregular, that is not significant enough for attribution.
• If you've changed much of the wording on the page or rearranged entire subsections to make it more tractable, that is significant enough for attribution.

Every page should begin with a byline. This byline uses a template, like so:

{{A Beginner's Guide to D/Written|by=NAME}}

The above template becomes

Do multiple contributors simply by adding multiple names with the proper grammar:

{{A Beginner's Guide to D/Written|by=Gregor, Richard and Ken}}

Any significant contributor should add a name or pseudonym to the byline. If you prefer a pseudonym, put it in quotes:

If you've edited but not written a significant portion of the page, add an editor section as well, like so:

{{A Beginner's Guide to D/Edited|by=Gregor Richards}}

[edit] Complexity

Remember that this is A Beginner's Guide to D. So:

• Don't dwell on bizarre exceptions from rules. If they must be mentioned, mention them, but don't confuse the reader, who presumably doesn't know anything about programming.
• If you find yourself needing to refer to a future section to explain the current one, then the table of contents needs changing - every section should depend only on those preceding it.

[edit] Transitional Users

(The rules put forth in this section are yet to be officially accepted)

To make this book usable by seasoned programmers, templates are provided to show when certain content is redundant for certain users. These templates are:

{{A Beginner's Guide to D/Skim X}}

{{A Beginner's Guide to D/Skim J}}

{{A Beginner's Guide to D/Skim CX}}

{{A Beginner's Guide to D/Skim XJ}}

{{A Beginner's Guide to D/Skim CXJ}}

These templates should be at the top of sections, immediately after attribution, or at the top of a subsection if the rest of the section does not apply.