A Beginner's Guide to D/Style Guide

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.

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

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.

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:

Otherwise, use either the chapter stub:

or section stub:

{{sectstub}}

as appropriate.

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.

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.

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);
}

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

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.

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

Programmers familiar with C++ are likely to find this section familiar, and may want to skim or skip it at their discretion.

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

Programmers familiar with Java are likely to find this section familiar, and may want to skim or skip it at their discretion.

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

Programmers familiar with C or C++ are likely to find this section familiar, and may want to skim or skip it at their discretion.

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

Programmers familiar with C++ or Java are likely to find this section familiar, and may want to skim or skip it at their discretion.

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

Programmers familiar with C, C++ or Java are likely to find this section familiar, and may want to skim or skip it at their discretion.

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.