www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Re: Naming convention in Phobos

reply Jim <bitcirkel yahoo.com> writes:
Jonathan M Davis Wrote:

 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

All right, thanks for the courteous reply. Considering the other comments in this thread I think there isn't much interest in working out or agreeing on a few good principles or guidelines for naming identifiers in Phobos. Otherwise, even if we could only agree on a few of them, they could be written down somewhere, should anyone someday be inclined to join the development.
Mar 06 2011
next sibling parent Don <nospam nospam.com> writes:
Jim wrote:
 Jonathan M Davis Wrote:
 
 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?

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

All right, thanks for the courteous reply. Considering the other comments in this thread I think there isn't much interest in working out or agreeing on a few good principles or guidelines for naming identifiers in Phobos. Otherwise, even if we could only agree on a few of them, they could be written down somewhere, should anyone someday be inclined to join the development.

All future modules will undergo a review process which will prevent the worst naming examples. We will need to initiate a review of existing modules at some point. Until that's completed, it would seem to be a bit counterproductive to publish a list of rules that 80% of Phobos modules break... But in general, I agree with you.
Mar 06 2011
prev sibling next sibling parent reply Jonas Drewsen <jdrewsen nospam.com> writes:
On 06/03/11 18.50, Jim wrote:
 Jonathan M Davis Wrote:

 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

All right, thanks for the courteous reply. Considering the other comments in this thread I think there isn't much interest in working out or agreeing on a few good principles or guidelines for naming identifiers in Phobos. Otherwise, even if we could only agree on a few of them, they could be written down somewhere, should anyone someday be inclined to join the development.

Funny you mention it. I was actually looking for such guidelines a couple of days ago on both digitalmars.com and d-programming-language. I ended up having to look at the phobos source code to get an idea of the style. So thumbs up from here on having such guidelines. /Jonas
Mar 07 2011
next sibling parent reply %u <wfunction hotmail.com> writes:
 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

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. I don't like the idea that enum values (which are constants) would also be camelCased; I think they should be PascalCased. Why? Simply because something like: enum InteropKind { import, export } won't compile. Furthermore, these aren't "variables" (they can't vary *at all*, even through casts -- unlike immutables) so I think enum values should be CamelCased. (PLEASE DO NOT USE ALL CAPS as it has no real benefit, and since it needlessly forces the use of underscores.) Another issue: Whatever the naming scheme is, please make sure that it's _specific enough_ that it won't conflict with other imports through reasonable use. E.g. don't make a function in std.path called getName() to get a file's name, because someone who's unaware of this could easily call getName() for a totally different module (say, hypothetically, on an Exception) and it would confuse the heck out of the reader. In this case, I'd say it should be getFileName(). If there's a lot of good choices, then I'd say that using a camelCased version of what Microsoft does in .NET would be a good idea; e.g. getFullPath(), isPathRooted(), getTempFileName(), getDirectoryName(), etc. Just my take on this... any thoughts?
Mar 07 2011
parent reply %u <wfunction hotmail.com> writes:
 I don't think I understand your reasoning.  Enum members can't

capitalised? You could equally well use this argument for *all* D symbols... Yes, we could (and in fact, I'd advocate for a D version of C#'s symbol for marking keywords as identifiers). However, the thing is that this happens _so_ often with enums that I think it's worth making it an exception. As soon as you start to write some sort of code that has to do anything remotely with programming, you can say something like: enum TypeCode { int, long, bool } as those are the most logical choices (and thinking around them is a bit difficult.) But you don't often really name a variable "int", so it's not so much as an issue with variables as with enums IMHO.
Mar 08 2011
parent %u <wfunction hotmail.com> writes:
 Fortunately, these are "very not" any kind of <<most logical

(imo) according to plain common sense. I have the same kind of use case as you, apparently (including even a 'TypeCodes' enum!), and thank to D's very weird naming, /I/ can use sensible names for enum members and various other symbol series, without resorting to a kind of prefix code or such. // same names as in the source language, thanx! enum TypeCodes { Integer, Real, Text, Logical, Array, ... } Noticed that you capitalized "real", which would have collided with the keyword. (My point wasn't that "long" was the best name, but that this situation obviously occurs often enough to merit consideration of a different casing convention.)
Mar 08 2011
prev sibling parent "Lars T. Kyllingstad" <public kyllingen.NOSPAMnet> writes:
On Mon, 07 Mar 2011 09:36:11 +0000, %u wrote:

 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

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. I don't like the idea that enum values (which are constants) would also be camelCased; I think they should be PascalCased. Why? Simply because something like: enum InteropKind { import, export } won't compile.

I don't think I understand your reasoning. Enum members can't have names which are also keywords, hence enums should be capitalised? You could equally well use this argument for *all* D symbols...
 Furthermore, these aren't "variables" (they can't vary
 *at all*, even through casts -- unlike immutables) so I think enum
 values should be CamelCased. (PLEASE DO NOT USE ALL CAPS as it has no
 real benefit, and since it needlessly forces the use of underscores.)

I don't think the distinction is between variables and non-variables. Rather, the distinction is between functions and values on one side and types on the other. Functions and values are camel-cased, while types are capitalised. That leaves the question about how to name templates. In Phobos, the rule is extended to templates as follows: camelCase: - function templates - templates that evaluate to values Capitalise: - mixin templates - class/struct templates -Lars -Lars
Mar 07 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 03/08/2011 11:00 AM, %u wrote:
 I don't think I understand your reasoning.  Enum members can't

capitalised? You could equally well use this argument for *all* D symbols... Yes, we could (and in fact, I'd advocate for a D version of C#'s symbol for marking keywords as identifiers). However, the thing is that this happens _so_ often with enums that I think it's worth making it an exception. As soon as you start to write some sort of code that has to do anything remotely with programming, you can say something like: enum TypeCode { int, long, bool } as those are the most logical choices (and thinking around them is a bit difficult.) But you don't often really name a variable "int", so it's not so much as an issue with variables as with enums IMHO.

Fortunately, these are "very not" any kind of <<most logical choices>>. Neither according to D's own naming convention, nore (imo) according to plain common sense. I have the same kind of use case as you, apparently (including even a 'TypeCodes' enum!), and thank to D's very weird naming, /I/ can use sensible names for enum members and various other symbol series, without resorting to a kind of prefix code or such. // same names as in the source language, thanx! enum TypeCodes { Integer, Real, Text, Logical, Array, ... } Denis -- _________________ vita es estrany spir.wikidot.com
Mar 08 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 03/08/2011 07:28 PM, %u wrote:
 Fortunately, these are "very not" any kind of<<most logical

(imo) according to plain common sense. I have the same kind of use case as you, apparently (including even a 'TypeCodes' enum!), and thank to D's very weird naming, /I/ can use sensible names for enum members and various other symbol series, without resorting to a kind of prefix code or such. // same names as in the source language, thanx! enum TypeCodes { Integer, Real, Text, Logical, Array, ... } Noticed that you capitalized "real", which would have collided with the keyword. (My point wasn't that "long" was the best name, but that this situation obviously occurs often enough to merit consideration of a different casing convention.)

Right. Did not even know "Real" is a keyword ;-) (the above list is not copied from my 'real' code). Denis -- _________________ vita es estrany spir.wikidot.com
Mar 08 2011
prev sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Tuesday, March 08, 2011 10:28:11 %u wrote:
 Fortunately, these are "very not" any kind of <<most logical

choices>>. Neither according to D's own naming convention, nore (imo) according to plain common sense. I have the same kind of use case as you, apparently (including even a 'TypeCodes' enum!), and thank to D's very weird naming, /I/ can use sensible names for enum members and various other symbol series, without resorting to a kind of prefix code or such. // same names as in the source language, thanx! enum TypeCodes { Integer, Real, Text, Logical, Array, ... } Noticed that you capitalized "real", which would have collided with the keyword. (My point wasn't that "long" was the best name, but that this situation obviously occurs often enough to merit consideration of a different casing convention.)

I have _never_ needed to use a primitive type's name (which is obviously a keyword) in an enum. _Never_. I'd be very surprised if Phobos ever needed to. I have a _very_ hard time believing that this is a common thing to do. And if type codes is your example, well type codes are generally considered to be bad practice, so I don't really see them as much of a supporting argument. Regardless, no matter what your naming conventions are, you're going to run into places where they don't work quite as well as you'd like. The naming conventions that we've been using for Phobos have generally been working quite well. The problem is generally that older Phobos code doesn't follow them, but that's slowly being fixed. What we've been doing works. And while I think that D code in general should follow similar naming conventions, you _are_ perfectly free to use whatever naming conventions you like in your own code. - Jonathan M Davis
Mar 08 2011