[phobos] Initial Phobos style guide proposal

[Don Clugston]

Non-bikeshed issue!

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

This is good for aggregate types and named enums,  but applying the
same rule for manifest constants is too strict.
(Please note that manifest constants are not the same as members of
named enums).
It's a particular problem for mathematical constants and values derived from C.

Generally speaking, camelCase works very poorly for global values
which are single words, because they are indistinguishable from
lowercase.
This isn't really a problem for functions, since you still have the
parentheses (All functions use camelCase, so if it is a function call,
it must be camelCase!)
Furthermore, I don't think there should be any global variables which
are single words, so it's really only an issue for manifest constants.
It is also potentially an issue for static functions defined at global
scope, which are callable using property syntax, but this is easier to
fix: such beasts, if ever truly necessary, should not be single words.
You need a very good reason for defining a value in global scope. And
an even better reason to have one which is only one word long. But
some do exist.
The classic examples are E and PI.

Java's style guide (the one from Sun) states:
The names of variables declared class constants and of ANSI constants
should be all uppercase with words separated by underscores ("_").
(ANSI constants should be avoided, for ease of debugging.)
To the best of my knowledge Python, Perl, Ruby, C, C++ all do the same.

IMHO we need a very, very good reason to do something different. And I
don't think any other option can realistically be consistent. As well
as the math constants, consider the Windows headers (and pretty much
anything else derived from C).

Please note that I think we should strongly discourage naked constants
defined at global scope. So I would hope that the issue doesn't arise
very often.
Thus, I propose:

- global variables, and static functions defined in global scope which
are callable using property syntax, must have names which are more
than word long.
- public manifest constants defined in global scope should generally
be avoided. When they do need to exist, they should have names which
are all uppercase.