Review of std.net.isemail part 2

[Jonathan M Davis]

On 2011-03-30 11:19, Daniel Gibson wrote:
> Am 30.03.2011 20:15, schrieb Don:
> > Lars T. Kyllingstad wrote:
> >> On Wed, 30 Mar 2011 15:04:49 +0200, Don wrote:
> >>> Lars T. Kyllingstad wrote:
> >>>> On Wed, 30 Mar 2011 13:23:02 +0200, Don wrote:
> >>>>> Jonathan M Davis wrote:
> >>>>>> On 2011-03-30 01:27, Jacob Carlborg wrote:
> >>>>>>> On 3/30/11 1:30 AM, Jesse Phillips wrote:
> >>>>>>>> Jacob Carlborg Wrote:
> >>>>>>>>> I've made a few minor changes:
> >>>>>>>>> 
> >>>>>>>>> * Renamed EmailStatusCode.Off -> None and On -> Any * Added and
> >>>>>>>>> clarified the documentation for EmailStatusCode.Any and None *
> >>>>>>>>> Updated the documentation
> >>>>>>>>> 
> >>>>>>>>> Github: https://github.com/jacob-carlborg/phobos/tree/isemail
> >>>>>>>>> Docs: http://dl.dropbox.com/u/18386187/isemail.html
> >>>>>>>>> 
> >>>>>>>>> --
> >>>>>>>>> /Jacob Carlborg
> >>>>>>>> 
> >>>>>>>> I believe enum values are to be named lowercase first.
> >>>>>>>> EmailStatusCode.any
> >>>>>>> 
> >>>>>>> I don't know what the style guide says about enum members but if
> >>>>>>> that's the case I'll change the names to begin with lowercase.
> >>>>>> 
> >>>>>> All names are camelcased.
> >>>>> 
> >>>>> That's not true. ALLCAPS is relatively common in Phobos. There is
> >>>>> absolutely no way PI is going to become pi.
> >>>>> 
> >>>>>> All type names begin with an uppercase letter, and all variables
> >>>>>> begin with a lowercase letter (with the possible exception of
> >>>>>> private member variables beginning with _ - but what's private to a
> >>>>>> class or struct isn't as critical as the public API regardless).
> >>>>> 
> >>>>> That part is clear.
> >>>>> 
> >>>>> > enum values fall in the same camp as variables.
> >>>>> 
> >>>>> I never heard that before, and it doesn't seem to be true throughout
> >>>>> Phobos. Grepping for all enum declarations (there isn't very many of
> >>>>> them actually), I found some which were like that, some which start
> >>>>> with uppercase, and some which are all caps.
> >>>>> 
> >>>>> I think you're assuming more concensus on style than has ever
> >>>>> actually been discussed.
> >>>> 
> >>>> I think Andrei introduced the camelCase enum convention with his
> >>>> Phobos overhaul back in 2.029. All new modules, and most modules
> >>>> which have seen major changes since then, follow it -- at least in
> >>>> the public API. Examples include std.algorithm, std.datetime,
> >>>> std.file, std.getopt, std.range and std.stdio.
> >>>> 
> >>>> I wouldn't mind if PI became pi -- I'd never dream of naming a
> >>>> variable pi anyway, unless it's actually supposed to represent π.
> >>>> Renaming E to e, on the other hand, that's a lot worse.
> >>>> 
> >>>> -Lars
> >>> 
> >>> Hardly. The only examples I could find were algorithm: SwapStrategy,
> >>> SortOutput
> >>> range: traverseOptions, SearchPolicy
> >>> There are many more which use other conventions, in other modules.
> >> 
> >> I don't intend to start a big debate about this, but I don't think you
> >> looked very hard. All of the modules I mentioned follow the camelCase
> >> convention, and as far as I can tell, none have public enums that
> >> follow other conventions.
> >> 
> >> std.algorithm: OpenRight, EditOp, SwapStrategy, SortOutput
> >> 
> >> std.datetime: Month, DayOfWeek, AllowDayOverflow, Direction, PopFirst,
> >> AutoStart
> >> std.file: SpanMode
> >> 
> >> std.getopt: config (actually not conventional, should be Config, but
> >> its members are still camelCased)
> >> 
> >> std.range: StoppingPolicy, TransverseOptions, SearchPolicy
> >> 
> >> std.stdio: KeepTerminator
> >> 
> >>> Note that manifest constants (eg, enum int XXX = value;) are completely
> >>> different to enumerated types (eg, enum XXX { AAA, BBB, CCC } ) They're
> >>> using a keyword in common, but they're quite different concepts.
> >> 
> >> I think a sensible rule is that types (and templates that evaluate to
> >> types) start with a capital letter, while values (and
> >> functions/templates that evaluate to values) are camelCased.
> >> 
> >> -Lars
> > 
> > The point is this: we do NOT have a style guide.
> > We have consensus on a few things. Types start with a capital letter.
> > Functions are camelCased. Many other things haven't actually been
> > discussed and agreed to.
> > 
> > Note that simplistic rules are doomed to failure. For example, template
> > aliases can be either values or types.
> > 
> > Also, any attempt to use precedent is a disaster since Phobos began as a
> > complete mishmash of styles. In some cases people erroneously believed
> > there was a convention, and attempted to adhere to it, even though no
> > such convention existed.
> > 
> > We desperately need a style guide containing all the things which have
> > actually been agreed to (and equally importantly, nothing which hasn't).
> > The simplest thing to do would be to fix up the existing one on the
> > website which nobody follows.
> 
> What about http://digitalmars.com/d/2.0/dstyle.html ?

That would be the "existing one on the website which nobody follows." It's 
actually not all that far off from what Phobos actually does, but it's not 
really actually followed, and it wasn't agreed on by the Phobos devs. Also, 
what we're looking for is a _Phobos_ style guide, not a _D_ style guide. To 
some extent at least, it would be nice if a lot of Phobos' conventions 
(particularly naming conventions) were used by the community at large, but 
we're not looking to enforce that at all. What we're looking for is 
consistency within Phobos. And we need an actual style guide for that, since 
even if all of the current Phobos devs agree on a set of conventions and 
follow them religiously, no one new to the team or who is writing code with 
the hope of getting it into Phobos is necessarily going to be aware of those 
conventions.

- Jonathan M Davis