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.

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 ?

On Wed, 30 Mar 2011 20:19:36 +0200, Daniel Gibson <metalcaedes@gmail.com> wrote:

>> 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 document has little to do with actual D code written and included in
Phobos or elsewhere. We really need a new guide.

-- 
Simen

On 2011-03-30 20:15, Don wrote:
> 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.

So, should I change the enum members to start with lowercase or leave it like it is?

-- 
/Jacob Carlborg

On 2011-03-30 11:47, Jacob Carlborg wrote:
> On 2011-03-30 20:15, Don wrote:
> > 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.
> 
> So, should I change the enum members to start with lowercase or leave it like it is?

I would say to change it to start with lowercase. That's what all of the newer Phobos code does.

- Jonathan M Davis

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

On 2011-03-30 11:15, Don wrote:
> 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.

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 don't think that he's entirely against it, but we do keep running into issues where someone codes something one way and Andrei and/or others expect it to be another and are unhappy that it is (e.g. the 80 character line limit).

We don't need anything super strict or which specifies everything in insane detail, but basic style guidelines would definitely be a good thing to have. Maybe I should just put one together and post it on the Phobos list for discussion.

- Jonathan M Davis

On Mar 31, 11 02:22, Simen kjaeraas wrote:
> On Wed, 30 Mar 2011 20:19:36 +0200, Daniel Gibson
> <metalcaedes@gmail.com> wrote:
>
>>> 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 document has little to do with actual D code written and included in
> Phobos or elsewhere. We really need a new guide.
>

Is this still the case? The issue has been brought up several times in this NG and I thought it should have been fixed.

Except 'Two blank lines separating function bodies' the new Phobos modules (just looking at container.d) conform to this style guide quite well.

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.

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.

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.

- 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

On 2011-03-30 13:07, 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.

I'll throw something together within the next day or two. It shouldn't take long. What'll be harder is getting people to actually read it and agree on it. Most discussions on this sort of thing in the past haven't generated much discussion even when people seem to definitely care (of course, the Phobos list seems pretty quiet of late, and the general activity for commits to Phobos from the Phobos dev team as a whole seems pretty low ever since we switched to git - whether that's the switch is related or not, I don't know). Still, we should get something going. The more that people are looking to contribute to Phobos, the clearer that we need to be on style requirements and guidelines.

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

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

Some of these are certainly debatable, but are overall good. We can discuss it as part of reviewing an actual style document though.

- Jonathan M Davis