On Tue, Jul 16, 2013 at 12:52:21AM +0200, Joseph Rushton Wakeling wrote:
> Hello all,
> 
> Quick query -- what's the preferred template variable name for a range type?
> 
> I've seen both R and Range used as options but want to confirm if there's a preference for one or the other.  It occurs to me that Range might potentially clash with some library or user-created entity.
[...]

I don't think it matters in this case, as the name would only be visible within the scope of the template, and AFAICT would shadow any external definitions, so you shouldn't get into trouble with it.

I generally use R 'cos it's less typing and I'm lazy, but Walter has
been recently of the opinion that a more descriptive name is necessary
for ddoc purposes, e.g., MyStruct(InputRange)(InputRange r) is much more
self-documenting than MyStruct(R)(R r). Template signatures aren't
included in ddoc output IIRC, so this can be an important consideration.


T

-- 
Today's society is one of specialization: as you grow, you learn more and more about less and less. Eventually, you know everything about nothing.

On 07/16/2013 01:02 AM, H. S. Teoh wrote:
> I generally use R 'cos it's less typing and I'm lazy

... ditto ... :-)

> but Walter has been recently of the opinion that a more descriptive name
> is necessary for ddoc purposes, e.g., MyStruct(InputRange)(InputRange r)
> is much more self-documenting than MyStruct(R)(R r).

Yes, that was my main consideration for this case.  I'm worried about the potential for clashes with other elements of the namespace, though.

I'm thinking in particular of the tendency to use Random as the template parameter name for a random number generator, when Random is actually an alias for the default RNG type.  I've proposed a blanket rewrite of such template parameter names to Rng: http://d.puremagic.com/issues/show_bug.cgi?id=10434

Particular context is that I'm trying to tidy up/standardize some bits of std.random and I'd like my standards to be future-proof. :-)

On Mon, Jul 15, 2013 at 4:02 PM, H. S. Teoh <hsteoh@quickfur.ath.cx> wrote:

> On Tue, Jul 16, 2013 at 12:52:21AM +0200, Joseph Rushton Wakeling wrote:
> > Hello all,
> >
> > Quick query -- what's the preferred template variable name for a range
> type?
> >
> > I've seen both R and Range used as options but want to confirm if
> there's a
> > preference for one or the other.  It occurs to me that Range might
> potentially
> > clash with some library or user-created entity.
> [...]
>
> I don't think it matters in this case, as the name would only be visible within the scope of the template, and AFAICT would shadow any external definitions, so you shouldn't get into trouble with it.
>
> I generally use R 'cos it's less typing and I'm lazy, but Walter has
> been recently of the opinion that a more descriptive name is necessary
> for ddoc purposes, e.g., MyStruct(InputRange)(InputRange r) is much more
> self-documenting than MyStruct(R)(R r). Template signatures aren't
> included in ddoc output IIRC, so this can be an important consideration.
>
>
Using Range is vague (inputRange? etc) anyways so might as well use R. Including template constraints in generated doc would make this a non-issue.

I don't understand the rationale for not including them. I've raised the issue before, see [1].

For example in http://dlang.org/phobos/std_algorithm.html we have:

----
void reverse(Range)(Range r);

void reverse(Range)(Range r);
----
which is really not helpful.
It should show full signature:

----
void reverse(Range)(Range r) if (isBidirectionalRange!Range &&
!isRandomAccessRange!Range && hasSwappableElements!Range)

void reverse(Range)(Range r) if (isRandomAccessRange!Range &&
hasLength!Range)
----

and even better, with shorter type:
----
void reverse(R)(R r) if (isBidirectionalRange!R && !isRandomAccessRange!R
&& hasSwappableElements!R)

void reverse(R)(R r) if (isRandomAccessRange!R && hasLength!R)
----



[1]: implicit template constraint notation : http://forum.dlang.org/post/mailman.1006.1370836279.13711.digitalmars-d@puremagic.com ).

On Monday, 15 July 2013 at 23:03:45 UTC, H. S. Teoh wrote:
> I generally use R 'cos it's less typing and I'm lazy, but Walter has
> been recently of the opinion that a more descriptive name is necessary
> for ddoc purposes, e.g., MyStruct(InputRange)(InputRange r)

One thing about that is that the type is being encoded into the name of the template parameter. Ideally, the type shouldn't be important, with the template constraints documenting anything noteworthy. With MyStruct, for example, I think MyStruct(Range)(Range r) would be better than the former, as it's more general. Then a template constraint such as if(isInputRange!Range) documents that the type must be at least an input range.

On Monday, 15 July 2013 at 23:09:59 UTC, Joseph Rushton Wakeling wrote:
> On 07/16/2013 01:02 AM, H. S. Teoh wrote:
>> I generally use R 'cos it's less typing and I'm lazy
>
> ... ditto ... :-)
>
>> but Walter has been recently of the opinion that a more descriptive name
>> is necessary for ddoc purposes, e.g., MyStruct(InputRange)(InputRange r)
>> is much more self-documenting than MyStruct(R)(R r).
>
> Yes, that was my main consideration for this case.  I'm worried about the
> potential for clashes with other elements of the namespace, though.
>
> I'm thinking in particular of the tendency to use Random as the template
> parameter name for a random number generator, when Random is actually an alias
> for the default RNG type.  I've proposed a blanket rewrite of such template
> parameter names to Rng: http://d.puremagic.com/issues/show_bug.cgi?id=10434
>
> Particular context is that I'm trying to tidy up/standardize some bits of
> std.random and I'd like my standards to be future-proof. :-)

struct SomeRangeWrapper(Range)
{
    alias R = Range;
    //...
}

Fixed.

I think "Range" is better, because it shows up in the docs, and is a bit clearer than "R" (although anybody doing D should understand it). But when working, "R" is easier. The above approach solves both.