Naming convention in Phobos

[Jonathan M Davis]

On Sunday 06 March 2011 02:59:25 Jim wrote:
> Okay, so there's a discussion about identifier names in the proposed
> std.path replacement -- should they be abbreviated or not? Should we
> perhaps seek to have a consistent naming convention for all identifier
> names in Phobos?
> 
> 
> Some of the potential benefits:
> 
> • Legibility, understandability and clarity (reduce ambiguity).
> • Ease in finding a suitable function/class by name.
> • Knowing if it's a cheap or costly function call.
> • Aesthetics and professional appearance.
> 
> 
> Some properties that I can think of for discussion:
> 
> • Abbreviation (and if so, what to abbreviate and how much)?
> • Preference of commonly used terms in other languages, contexts?
> • Use of get and set prefixes or not (getName() or simply name())?
> • Explicit use of a prefix (example: calc or calculate) for costly
> operations? • Naming of function and template arguments?
> • Uppercase, lowercase, camelcase, underscore in multi-word names? All caps
> for constants, or different appearance for different types (types,
> functions, arguments, constants...). What about acronyms: TCP, Tcp?
> 
> Are there other concerns?

The general naming convention as far as variable names go is camelcased with the 
name starting with a lower case letter - this includes constants. Most of Phobos 
follows this, and the parts that haven't been have been moving towards it. There 
are likely to be a few exceptions, but on the whole, that's how it's supposed to 
be. Type names are the same, except they start with an upper case letter (this 
includes enum names - the enum values are capitalized the same as any other 
variables however). That's the way it has been, and that's the way that it's 
pretty much guaranteed to stay.

Generally speaking, we want descriptive names, and I think that it's safe to say 
that we don't want overly long names, so if we can have descriptive but short 
names, that's generally best. get and set prefixes are likely to be rare, because 
most of such functions will be properties, and properties will normally have 
nouns for names and won't use get or set, but I don't think that we want to say 
that we'll _never_ have function names prefixed with get or set. Normally, we 
won't, but it's going to be very situation-dependent.

Now, as for the rest of it, I don't really want to get into a big discussion of 
the best way to name everything. It's far too context-dependent and very quickly 
turns towards bike shedding. I think that it's appropriate for anyone who's 
developing a module for Phobos to come up with names that they think are 
reasonable and which follow the very basic naming conventions that we follow, 
and then have names adjusted as needed during the review process. I really don't 
think that we're going to get much of value by having a big discussion over 
general naming conventions. It seems to me like it's just going to be a classic 
situation for bike shedding and generally useless discussion. What we've been 
doing generally works just fine.

- Jonathan M Davis