On Mar 31, 11 04:35, Jonathan M Davis wrote:
>> >  For my money, just take the first that applies:
>> >
>> >  - Is it a function name? Use thisStyle.
>> >
>> >  - Is it a value (be it constant or variable)? Use thisStyle.
>> >
>> >  - Is it a type? Use ThisStyle.
>> >
>> >  - Is it a module name? Use this_style.
> This would be a good example of something that's never been agreed on AFAIK.
> Does any module in Phobos use this_style? I'm not necessarily opposed, but I
> don't think that it's been used yet.
>

It is more like 'thisstyle'

std.
   bigint
   bitmanip
   datetime
   getopt
   outbuffer
   outofmemory   // <-- btw why is it thing still documented?
   socketstream
   typecons
   typetuple

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

Andrei:

> Beyond naming:

Some standard for member attributes? Like m_something, etc? I don't like this a lot, but having a style guide on this too is useful for Phobos (and user code).

Bye,
bearophile

On 3/30/11 5:24 PM, bearophile wrote:
> Andrei:
>
>> Beyond naming:
>
> Some standard for member attributes? Like m_something, etc? I don't like this a lot, but having a style guide on this too is useful for Phobos (and user code).
>
> Bye,
> bearophile

I usually prepend private data members with an underscore.

Andrei

On 2011-03-30 15:27, Andrei Alexandrescu wrote:
> On 3/30/11 5:24 PM, bearophile wrote:
> > Andrei:
> >> Beyond naming:
> > Some standard for member attributes? Like m_something, etc? I don't like this a lot, but having a style guide on this too is useful for Phobos (and user code).
> > 
> > Bye,
> > bearophile
> 
> I usually prepend private data members with an underscore.

That's what std.datetime and std.file do. Regardless, member variables often need a different naming scheme from normal variables thanks to properties that have the same name. That can go in the style guide, but I don't think that the naming scheme for private member variables or local variables is as important as the public ones, since they're part of the API. It would still be good to be consistent (like it's good to be consistent with braces), but when it comes to names, the primary concern is the public API.

- Jonathan M Davis

On 3/30/2011 6:24 PM, bearophile wrote:
> Andrei:
>
>> Beyond naming:
>
> Some standard for member attributes? Like m_something, etc? I don't like this a lot, but having a style guide on this too is useful for Phobos (and user code).
>
> Bye,
> bearophile

I think the style guide should be focused mostly (though not exclusively) on things that affect the public interface.  Things like naming conventions for private member variables are minor details and not worth being bureaucratic about.

Am 31.03.2011 01:57, schrieb dsimcha:
> On 3/30/2011 6:24 PM, bearophile wrote:
>> Andrei:
>>
>>> Beyond naming:
>>
>> Some standard for member attributes? Like m_something, etc? I don't
>> like this a lot, but having a style guide on this too is useful for
>> Phobos (and user code).
>>
>> Bye,
>> bearophile
>
> I think the style guide should be focused mostly (though not
> exclusively) on things that affect the public interface. Things like
> naming conventions for private member variables are minor details and
> not worth being bureaucratic about.

Well, I remember a lengthy discussion on the maximum line length in Phobos, so it seems like stuff that isn't visible from the public interface still seems to bother people (including Andrei).

On 2011-03-30 17:17, Daniel Gibson wrote:
> Am 31.03.2011 01:57, schrieb dsimcha:
> > On 3/30/2011 6:24 PM, bearophile wrote:
> >> Andrei:
> >>> Beyond naming:
> >> Some standard for member attributes? Like m_something, etc? I don't like this a lot, but having a style guide on this too is useful for Phobos (and user code).
> >> 
> >> Bye,
> >> bearophile
> > 
> > I think the style guide should be focused mostly (though not exclusively) on things that affect the public interface. Things like naming conventions for private member variables are minor details and not worth being bureaucratic about.
> 
> Well, I remember a lengthy discussion on the maximum line length in Phobos, so it seems like stuff that isn't visible from the public interface still seems to bother people (including Andrei).

If you look at Andrei's post in this thread where he lists the beginnings of a possible style guide, _most_ of it is stuff that's not part of the public API.

- Jonathan M Davis

On 3/30/11 9:42 PM, Andrei Alexandrescu wrote:
> On 3/30/11 1:47 PM, Jacob Carlborg wrote:
>> So, should I change the enum members to start with lowercase or leave it
>> like it is?
>
> Change please.
>
> Thanks,
>
> Andrei

Ok, will do.

-- 
/Jacob Carlborg

On 3/30/11 10:07 PM, Andrei Alexandrescu wrote:
> On 3/30/11 2:47 PM, Jonathan M Davis wrote:
>> I've tried to get Andrei to agree to a style guide a few times, but he's
>> generally pushed back on it. I definitely think that we should have
>> one if we
>> want to actually have a consistent style, but thus far, he hasn't
>> agreed to
>> have one.
>
> I think that's not representing my viewpoint quite accurately, but
> getting to the bottom of whatever misunderstanding was there is not
> important.
>
> It would be helpful to have a broad style guide. The existing one is a
> good start and is in fact already observed by much of Phobos (and in
> particular by most of my code). The problem with writing a more
> elaborate guide is finding the person(s) with the time and inclination
> to write a draft, get it vetted by the major contributors, and take it
> to completion.

Which one is the existing one, it it available on the DigitalMars site?

> For my money, just take the first that applies:
>
> - Is it a function name? Use thisStyle.
>
> - Is it a value (be it constant or variable)? Use thisStyle.
>
> - Is it a type? Use ThisStyle.
>
> - Is it a module name? Use this_style.
>
> Beyond naming:
>
> - Define variables as late as possible.
>
> - Define constants and other names scoped appropriately.
>
> - 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.

I don't like this one. I would say prefer readable code to compact code. Don't be afraid of having long descriptive names of variables and having vertical space in your code. I don't mean you should put three newlines between two function declarations but I usually put a newline before and after statements:

int a;
int b;

foo();
bar();

if (a == b)
   foo();

else
   bar();

int c = 3;

> Nitpicks that 9 people have 10 opinions of:
>
> - No 2+ empty lines please. Within a function, an empty line at best
> should be replaced by a comment describing the meaning of the next block.
>
> - Try to fit functions loosely on one editor page.
>
> - Brace on its own line. (In fact I don't care much either way, but this
> is the way the majority of the code is.) Note that this does cost more
> vertical space so it somewhat clashes with the previous point.
>
> - Please avoid > 80 columns unless you feel it induces sterility in the
> long term.

Do you know how narrow 80 columns look on a wide screen. I think it looks narrow on a regular (non-wide) screen.

> - No tabs please.
>
> - 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).
>
>
> Thanks,
>
> Andrei


-- 
/Jacob Carlborg