[phobos] Initial Phobos style guide proposal

[Jonathan M Davis]

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

I believe that the main reason that we haven't been using all caps is that you 
end up using constants more in D than you might in other languages 
(particularly given the power of CTFE), and it gets really annoying if you 
frequently have to use variables which are in all caps. Certainly, that's why 
Andrei has pushed for them to be named like normal variables.

In the case of the values of named enums, you have to use the enum's name when 
referencing them anyway, so there's no real gain to naming them differently 
than you would a public member variable or property.

In the case of local variables which are manifest constants, then there's no 
real gain in using anything other than the normal variable naming scheme, and 
their not part of the public API anyway, so worrying about them doesn't really 
seem necessary.

The question is what to do with public manifest constants. For classes and 
structs, I think that it's likely best to use the normal variable naming 
scheme, since they're effectively properties of the type. But for 
global/module level manifest constants, that's a bit different, and I'm a bit 
divided on it. For something like pi, I think that it makes perfect sense that 
it would be PI. But take some of the constants in std.string like digits or 
letters - or even whitespace. They're one word long (which could be debated 
with whitespace, but as a programming language term, it's one word), but you 
don't really gain much by making them all uppercase: LETTERS, DIGITS, 
WHITESPACE. And they get really ugly to use that way. So, I don't know.

It _is_ typical in C, C++, and Java (possibly C# too, but I don't remember) to 
use all caps for constants. I believe that that that's the case because 
they're typically macros in C, and it was necessary to differentiate them 
drastically from other naming conventions in order to avoid accidentally 
triggering them, and the convention carried over to newer languages such as 
Java, even though it was no longer necessary to avoid problems with macros. 
And in C or C++, if the constant is _not_ a macro, it's not generally in all 
caps, because then it could run into problems with macros. Such problems do 
not exist in D, since it doesn't have macros. So, macros don't force us to 
choose to use all caps for anything, and they don't force us to avoid them for 
anything.

I don't think that there's any question that global variables should be 
generally avoided, but there _are_ cases where global manifest constants make 
good sense (and they're definitely used in Phobos).

I do agree that short constants - particularly math constants - stand out 
better using all caps. But it's annoying once you get beyond a few letters - 
regardless of whether they're a single word or not. So, clearly we don't want 
to enforce that global manifest constants are _always_ named the same as 
normal variables, but I'm not sure that we want to enforce that single word 
global manifest constants be all caps either. This may be a case where we want 
to be a bit lenient and go with whatever works for a particular variable name. 
In some cases - when the name is particularly short - that's all caps. In 
others, it's the normal naming scheme.

- Jonathan M Davis