On 3/31/2011 1:10 PM, Jonathan M Davis wrote:
> Now, it's fine with me if we don't dictate how member variables are named - as long as it's understood that they will not always match the normal naming scheme. Personally, I use a leading underscore. I also don't like it when there's mixture of styles between private member variables (e.g. some with an underscore nad some without), but that's my personal preference. The only reason I see to select a style is if we want Phobos to be consistent. But while some people think that Phobos should be highly consistent in its styling throughout, I don't think that it necessarily matters. What matters is the public API. _That_ should strive for consistency, because that affects the users of the library. The style of the implementation details does not.
>

I tend to agree that the public API style is far, far more important than the implementation details.

On Thu, 31 Mar 2011, Walter Bright wrote:

> On 3/30/2011 8:00 PM, Jonathan M Davis wrote:
> > These are intended to be general guidelines which are followed most of the time but can be broken within reason (though hopefully that's relatively rare).
> > 
> 
> I'd like to see this as changes (as necessary) to the D style guide http://www.digitalmars.com/d/2.0/dstyle.html, not as something distinct and possibly in contradiction with it.

I see the same thing happening this time that has happened during last discussions.  There's a core part that's agreed upon, but it's overshadowed by the discussion about the parts that aren't, and nothing happens.  I highly suggest getting the agreed upon parts captured in an appropriate doc.  The above one would be fine by me.

It's far easier to add rules to an existing list once it exists.

My 2 cents,
Brad

On 1 apr 2011, at 04:49, Brad Roberts wrote:

> On Thu, 31 Mar 2011, Walter Bright wrote:
> 
>> On 3/30/2011 8:00 PM, Jonathan M Davis wrote:
>>> These are intended to be general guidelines which are followed most of the time but can be broken within reason (though hopefully that's relatively rare).
>>> 
>> 
>> I'd like to see this as changes (as necessary) to the D style guide http://www.digitalmars.com/d/2.0/dstyle.html, not as something distinct and possibly in contradiction with it.
> 
> I see the same thing happening this time that has happened during last discussions.  There's a core part that's agreed upon, but it's overshadowed by the discussion about the parts that aren't, and nothing happens.  I highly suggest getting the agreed upon parts captured in an appropriate doc.  The above one would be fine by me.
> 
> It's far easier to add rules to an existing list once it exists.
> 
> My 2 cents,
> Brad
> 
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos


That sounds reasonable to do. Put in the things we can agree on and leave the rest out.

-- 
/Jacob Carlborg

> 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

> On 3/30/2011 8:00 PM, Jonathan M Davis wrote:
> > These are intended to be general guidelines which are followed most of the time but can be broken within reason (though hopefully that's relatively rare).
> 
> I'd like to see this as changes (as necessary) to the D style guide http://www.digitalmars.com/d/2.0/dstyle.html, not as something distinct and possibly in contradiction with it.

Some of the itmes on the list (such as public symbol naming conventions) probably should go in an update to the D style guide. However, some of the others, don't really make sense there, and even if want want to follow them in Phobos, we still wouldn't want them in the D style guide - such as "Prefer ? : to if/else within reason," or "If you need to use a version block for documentation, use version(StdDoc), not version(D_Ddoc)." So, depending on what we settle on, we may need a second guide which lists specific additional stuff that applies specifically to Phobos (or we could add a section at the bottom of the current guide which was specific to Phobos). However, since most of the stuff that would need to be specific to Phobos is primarily stuff that details how code within a function should be written and there's definite resistance to having a style guide which lists that sort of thing, we may end up with a list which is pretty much just stuff which pertains to the public API and therefore fits just fine in the D style guide.

Regardless, the current D style guide should be updated based on what we decide for Phobos, or it should be gotten rid of. We shouldn't have an out-of- date guide like that sitting on the main site as if it's what we followed. So, either it needs to be what we follow, or it shouldn't be there.

- Jonathan M Davis