[phobos] Initial Phobos style guide proposal

[Jonathan M Davis]

It's become clear that we need at least a basic style guide for Phobos. While 
some of our coding conventions are clear and consistent, others vary depending 
on who's writing the code, and more importantly, new folks writing code for 
Phobos (be they new Phobos devs or simply writing code to be reviewed for 
inclusion in Phobos) need to be aware of the coding conventions that we 
follow. So, I've put one together based on what has previously been discussed, 
what we generally do in code, and what the online style guide says (though all 
I did with that for the most part was take some of its nicer points that we 
pretty much follow anyway).

This is obviously not set in stone. Rather it's the starting point for a 
discussion. In the first two sections (naming conventions and formatting 
conventions), _most_ of it has been agreed upon by the Phobos devs in general, 
as I understand it (though there are some areas - such as line length - which 
have _not_ been agreed upon). The last section, general coding guidelines, is 
mixture of what we already do and what Andrei has said that he wants to be the 
case (though I did tweak some of what he said - e.g. one of his posts implied 
that there shouldn't be _any_ empty lines in a function which leads to highly 
unreadable functions IMHO), so that is _definitely_ an area which is up for 
discussion. It might also be a bit long with items that are obvious enough 
that we can remove them, though the idea is to make what we expect in Phobos 
code clear.

These are intended to be general guidelines which are followed most of the 
time but can be broken within reason (though hopefully that's relatively 
rare).

============
Naming conventions
------------------
- Type names are camelcased and begin with an uppercase letter.

- Function and variable names and named values (including enum values) are
  camelcased and begin with a lowercase letter.

- Module names are all lowercase without camelcasing.

- Private member variables begin with an underscore.

- With templates, if they're for a type or result in a type, use the naming
  conventions for type names. If they generate a value, then use the naming
  conventions for variables. For template mixins, use the naming conventions
  for type names.

- Try to make names clear and descriptive, but avoid overly long names.
  Shorter names which are still appropriately descriptive are preferred.


Formatting Conventions
----------------------
- Don't use tabs. Use spaces.

- Indenting is 4 spaces.

- Braces go on their own line and line up.

- Commit code with unix line endings (though what you use in your editor
  is irrelevant).

- Try to make lines not exceed 80 characters, but it's not a hard limit.
  If it harms code readability to restrict it to 80 characters, then exceed
  80 characters, but if you go much beyond 80 characters, you really should
  break the line up.


General Coding Guidelines
-------------------------
- Don't put multiple statements on the same line.

- Restrict the scope of variables as much as reasonably possible and declare
  them as late as reasonably possible.

- Use enums for manifest constants, not const or immutable.

- Prefer anonymous temporaries to named values within reason.

- Prefer ? : to if/else within reason.

- Prefer compact, effective code to verbose code within reason. Make every
  line count.

- Avoid having 2+ empty lines in a row and reasonably minimize how many empty
  lines are within a function.

- Try to fit functions loosely on one editor page.

- Comments should be high level (describing 3-10 lines) instead of low-level
  (describing the mechanics of the next line, which are already obvious in
  code).

- Avoid meaningless aliases. Use aliases when reasonable, but we don't want
  to pollute the namespace with unnecessary aliases.

- Prefer to follow the convention that [] and * go with the type name rather
  than the variable name (e.g. int* a; instead of int *a;).

- Do not use Hungarian notation.

- All public declarations should have proper ddoc documentation.

- If you need to use a version block for documentation, use version(StdDoc),
  not version(D_Ddoc).

- DDoc documentation should be generatable for all OSes, so if you have
  multiple versions of a function for differing OSes or if a function doesn't
  exist on all OSes, then either put the version blocks within the function
  or use a version(StdDoc) with a declaration of the function (without a body)
  and the documentation.

- Unit test as much as is practical.

- Generally avoid using else with versions (as in else by itself, not
  else version(x)) with version blocks unless you use static assert(0) in
  the else block. We want to avoid cases where a new OS is used with Phobos
  and it uses the version block for another OS without a programmer properly
  looking at it and verifying that it's valid for the new OS.

- Make functions pure, nothrow, and const (if it's a member function) as much
  as reasonably possible, so that they work with pure, nothrow, and const
  code.

- Make as many function parameters const (or scope) as reasonably possible so
  that you can pass const and immutable values to them.


* Note: The rules in this style guide are guidelines which we want to be
        generally followed so that we have consistent code in Phobos, but
        they are not generally hard-and-fast rules which can never be broken.
        They are guidelines that we wish to follow. So, you can break them
        _within reason_ but should generally follow them.
============

Personally, I'd prefer a line's character limit to be more like 100 (if not 
more). I also like putting two empty lines between functions (as the old, 
online style guide says to do), so the restriction eliminating two empty lines 
in a row doesn't appeal to me. I also am not fond of the tendency of some 
(such as Andrei) to eliminate all extra vertical space within a function 
(though I do understand not wanting to have tons of empty lines in functions), 
and that combined with restrictions on line length is a nasty combination for 
code readability. _Most_ of the rest, I agree with. However, there are 
obviously going to be compromises made by pretty much everyone involved. What 
we need is a general consensus that we're generally willing to code to and 
which is clear.

So, that's my initial draft. After we've discussed it a bit and are more firm 
on what we want to do, I can create a version using DDoc which is nicer 
looking and can be put on the website if we want to.

- Jonathan M Davis