Steve Teale <steve.teale britseyeview.com> writes:

There's a growing tendency in Phobos documentation to use auto.

auto now = Clock.currTime();

Now I can understand that when the RHS is some obscure template, whose 
type might not be immediately obvious, the user should possibly be 
encouraged to RTFM. But if the outcome is deterministic I just have the 
feeling that documentation should provide information rather than hiding 
it.

OK, in Jonathan's example, this is preceded by a sentence that says that 
the result is a SysTime. But the auto made me forget, and wonder what it 
was, rather than reinforcing the preceding sentence.

I realize that this is probably a trivial point, but at the same time, in 
documentation, clarity is wonderful.

Steve

Dejan Lekic <dejan.lekic gmail.com> writes:

Steve, I agree 100%. Documentation should not have 'auto' unless it 
documents the 'auto' itself.

David Nadlinger <see klickverbot.at> writes:

On 11/5/11 7:01 PM, Dejan Lekic wrote:
 Steve, I agree 100%. Documentation should not have 'auto' unless it
 documents the 'auto' itself.

I generally agree, in that auto should be used judiciously in the docs, 
but the concerns imho only apply to cases where the type is not obvious 
anyway – for example, I think auto should still be used when 
initializing the variable with the result of a new expression.

David

Walter Bright <newshound2 digitalmars.com> writes:

On 11/5/2011 10:42 AM, Steve Teale wrote:
 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

 Now I can understand that when the RHS is some obscure template, whose
 type might not be immediately obvious, the user should possibly be
 encouraged to RTFM. But if the outcome is deterministic I just have the
 feeling that documentation should provide information rather than hiding
 it.

 OK, in Jonathan's example, this is preceded by a sentence that says that
 the result is a SysTime. But the auto made me forget, and wonder what it
 was, rather than reinforcing the preceding sentence.

 I realize that this is probably a trivial point, but at the same time, in
 documentation, clarity is wonderful.

I agree.

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:

On 11/5/11 1:48 PM, Walter Bright wrote:
 On 11/5/2011 10:42 AM, Steve Teale wrote:
 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

 Now I can understand that when the RHS is some obscure template, whose
 type might not be immediately obvious, the user should possibly be
 encouraged to RTFM. But if the outcome is deterministic I just have the
 feeling that documentation should provide information rather than hiding
 it.

 OK, in Jonathan's example, this is preceded by a sentence that says that
 the result is a SysTime. But the auto made me forget, and wonder what it
 was, rather than reinforcing the preceding sentence.

 I realize that this is probably a trivial point, but at the same time, in
 documentation, clarity is wonderful.

 I agree.

It's tricky. One simple fact that's been verified again and again is 
that documentation examples tend to be used a lot. They effectively are 
powerful style influencers for people learning the language.

If we avoid "auto" in documentation examples but we do use it in 
everyday code, we effectively foster a style that's foreign and 
non-idiomatic to newcomers.

Sample code should mimic real code. If real code would use auto, sample 
code should use auto.


Andrei

bearophile <bearophileHUGS lycos.com> writes:

Andrei Alexandrescu:

 If we avoid "auto" in documentation examples but we do use it in 
 everyday code, we effectively foster a style that's foreign and 
 non-idiomatic to newcomers.
 
 Sample code should mimic real code. If real code would use auto, sample 
 code should use auto.

D programmers are probably able to learn to use auto later, because it's handy,
it's an attractor. On the other hand one of the main purposes of the online
documentation is to be as clear as possible. D written by newbies is not the
same D written by D experts. But documentation must be written for D newbies
too, because they are ones that have more need of documentation. The code
written in the thousands of examples in the very good Pascal/Delphi docs was
written in a clear style that is not the same compact style an expert Delphi
programmer writes code. So I'd like D docs to avoid auto when the types are not
very clear. The purpose of the docs is not to shows examples of idiomatic D
code written by experts.

Bye,
bearophile

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:

On 11/5/11 3:02 PM, bearophile wrote:
 Andrei Alexandrescu:

 If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.

 Sample code should mimic real code. If real code would use auto,
 sample code should use auto.

 D programmers are probably able to learn to use auto later, because
 it's handy, it's an attractor. On the other hand one of the main
 purposes of the online documentation is to be as clear as possible. D
 written by newbies is not the same D written by D experts. But
 documentation must be written for D newbies too, because they are
 ones that have more need of documentation. The code written in the
 thousands of examples in the very good Pascal/Delphi docs was written
 in a clear style that is not the same compact style an expert Delphi
 programmer writes code. So I'd like D docs to avoid auto when the
 types are not very clear. The purpose of the docs is not to shows
 examples of idiomatic D code written by experts.

Patronizing one's reader is a common trap.

Andrei

bearophile <bearophileHUGS lycos.com> writes:

Andrei Alexandrescu:

 Patronizing one's reader is a common trap.

Please explain better, I don't understand.

One point I have not included in my precedent answer: I prefer "auto" in the D
docs also because I have a desire to know the types, so avoiding "auto" in the
docs is not just to help D newbies.

Bye,
bearophile

Tobias Pankrath <tobias pankrath.net> writes:

 
 Patronizing one's reader is a common trap.
 
 Andrei

Number one job of the docs is to provide good documentation and
showing advanced D style comes second.

Steve Teale <steve.teale britseyeview.com> writes:

On Sat, 05 Nov 2011 15:14:14 -0500, Andrei Alexandrescu wrote:

 If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.



Andrei,

I don't use auto in everyday code, in fact I don't think I've ever used 
it at all. I've been with D for some years now, but apparently I write 
'foreign and non-idiomatic' D. This goes just a tad beyond patronizing 
your reader.

Can you write us a brief article that will convince me of its benefits, 
and the error of my ways please. There's no Borders where I live, and 
Amazon does not deliver to Africa, so I don't have the benefit of your 
book.

Steve

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:

On 11/5/11 11:29 PM, Steve Teale wrote:
 On Sat, 05 Nov 2011 15:14:14 -0500, Andrei Alexandrescu wrote:

 If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.



 Andrei,

 I don't use auto in everyday code, in fact I don't think I've ever used
 it at all. I've been with D for some years now, but apparently I write
 'foreign and non-idiomatic' D. This goes just a tad beyond patronizing
 your reader.

It can be safely hypothesized you are, and you shouldn't be offended by 
seeing it stated. Patronizing one's reader is an unrelated thing - it 
means the author of some writing assumes being more knowledgeable than 
the readership.

 Can you write us a brief article that will convince me of its benefits,
 and the error of my ways please. There's no Borders where I live, and
 Amazon does not deliver to Africa, so I don't have the benefit of your
 book.

Unfortunately my schedule doesn't allow it, but sounds like a good 
article idea.


Andrei

Jonathan M Davis <jmdavisProg gmx.com> writes:

On Sunday, November 06, 2011 00:37:50 Andrei Alexandrescu wrote:
 On 11/5/11 11:29 PM, Steve Teale wrote:
 Can you write us a brief article that will convince me of its benefits,
 and the error of my ways please. There's no Borders where I live, and
 Amazon does not deliver to Africa, so I don't have the benefit of your
 book.

 
 Unfortunately my schedule doesn't allow it, but sounds like a good
 article idea.

A few of the reasons are

1. Some functions (especially those in std.algorithm) return templated types 
which you _don't_ want to have to type yourself or even worry about or care 
what they are beyond the fact that they're a range. auto makes such functions 
quite usable and useful whereas as they would be completely unreasonable 
otherwise. So, ranges in general definitely are used with auto.

2. With auto, if you change the type, you often don't have to change the code. 
For instance, if you have a function which returns a particular type, and you 
use auto, then if you change the type that it returns later and the new type 
has same API (or close enough that it doesn't matter for your code), then you 
don't have to change any of your code, whereas if you didn't use auto, you 
would. So, auto tends to make refactoring much easier.

3. Code tends to be more concise with auto. You avoid having to repeat the 
type name on both sides of the assignment operator.

I'm sure that there are more good reasons to use auto, but those are just a 
few of them that come immediately to mind. Honestly, when I first ran into 
auto, I didn't think that it was a big deal or that it was even necessarily a 
good idea, but after having used in code, I've found it to be _very_ useful. 
In fact, it drives me nuts when I can't use it in C++ - especially when you 
have to declare variables with types like vector<int>::iterator. I'll be 
_very_ glad when I get to use C++11 instead of C++98/03, since it adds auto. 
And actually, since it adds auto, you can probably find some good reasons for 
using it explained for C++11 if you go searching for them.

Overall, I just find that auto makes code cleaner, more legible, and easier to 
maintain. So, I pretty much always use it unless I can't (e.g. when a variable 
is default-initialized or when a variable's initializers defaults to the wrong 
type - which tends to happen with size_t). Perhaps, some examples should use 
it less in order to provide more clarity, but in general, I don't think that 
it's a big deal, because you can just look at the function's return type, 
which in most cases is right after the example that you're looking at, because 
the example is for the function in question.

- Jonathan M Davis

"Marco Leise" <Marco.Leise gmx.de> writes:

That's my cup of bike shedding!

Am 06.11.2011, 09:20 Uhr, schrieb Jonathan M Davis <jmdavisProg gmx.com>:

 A few of the reasons are

 1. Some functions (especially those in std.algorithm) return templated  
 types
 which you _don't_ want to have to type yourself or even worry about or  
 care
 what they are beyond the fact that they're a range. auto makes such  
 functions
 quite usable and useful whereas as they would be completely unreasonable
 otherwise. So, ranges in general definitely are used with auto.

No one disagrees on that auto must be used here.

 2. With auto, if you change the type, you often don't have to change the  
 code.
 For instance, if you have a function which returns a particular type,  
 and you
 use auto, then if you change the type that it returns later and the new  
 type
 has same API (or close enough that it doesn't matter for your code),  
 then you
 don't have to change any of your code, whereas if you didn't use auto,  
 you
 would. So, auto tends to make refactoring much easier.

Ok, I cannot really comment on that. It also hides some information, which  
could make it more difficult for someone else looking at the code to  
identify the used types. Then range templates are somewhat well-known. You  
know that what you get out is still a range of the type that you put in.

 3. Code tends to be more concise with auto. You avoid having to repeat  
 the
 type name on both sides of the assignment operator.

This is the ideal use case for auto and in DDOC it would not hide  
information. (Still I think it is a matter of personal taste and since I  
use to have a bad spelling I appreciate DDT to auto-complete method names,  
which doesn't currently work with auto ;) ).

It's not like we are discussing removing auto from the language specs.  
It's just that the documentation would benefit from explicit return types  
where they are proper types of their own, like TickDuration. I find it  
easier to comprehend how something works when I have less open questions  
to carry around while reading. Imagine the documentation of  
TickDuration.currAppTick() had an auto return type. Then the reader would  
have to look up in the source code if it returns a long or a TickDuration.  
That cannot be good.
On the other hand it could be that Steve would want that all occurrences  
of 'auto' are removed in the documentation. But I don't believe that.

Steve Teale <steve.teale britseyeview.com> writes:

 A few of the reasons are ...
 

Jonathan,

Thanks for stepping into the gap. I'm sure you are busy too.

I agreed with you in my original posting that template types were an 
exception, and I should also have excluded Thingie thing = new Thingie().

Your point 2) is convincing.

Steve

Somedude <lovelydear mailmetrash.com> writes:

Le 06/11/2011 05:29, Steve Teale a écrit :
 On Sat, 05 Nov 2011 15:14:14 -0500, Andrei Alexandrescu wrote:
 
 If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.



 
 Andrei,
 
 I don't use auto in everyday code, in fact I don't think I've ever used 
 it at all. I've been with D for some years now, but apparently I write 
 'foreign and non-idiomatic' D. This goes just a tad beyond patronizing 
 your reader.
 
 Can you write us a brief article that will convince me of its benefits, 
 and the error of my ways please. There's no Borders where I live, and 
 Amazon does not deliver to Africa, so I don't have the benefit of your 
 book.
 
 Steve

I would say auto removes a lot of redundancy in code, and redundancy is
usually bad.
I guess the best way to see its advantages is to rewrite some of your
code with auto everywhere you can. You should eventually see that the
code is far more legible and cleaner than before.
auto really is a small advantage that works wonders in this regard.
As Jonathan M. Davis stated very well, I expect it to have a huge impact
on C++11 code legibility, especially if it is used in libraries as well
as in application code.

Another reason, is it makes changing types easier, both for humans and
for automated tools, because you only have to change types where necessary.

Dude

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 06.11.2011, 10:19 Uhr, schrieb Somedude <lovelydear mailmetrash.com>:

 Another reason, is it makes changing types easier, both for humans and
 for automated tools, because you only have to change types where  
 necessary.

 Dude

minus automated tools. They have to implement support for both anyways.

"Steven Schveighoffer" <schveiguy yahoo.com> writes:

On Sun, 06 Nov 2011 00:29:57 -0400, Steve Teale  
<steve.teale britseyeview.com> wrote:

 On Sat, 05 Nov 2011 15:14:14 -0500, Andrei Alexandrescu wrote:

 If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.



 Andrei,

 I don't use auto in everyday code, in fact I don't think I've ever used
 it at all. I've been with D for some years now, but apparently I write
 'foreign and non-idiomatic' D. This goes just a tad beyond patronizing
 your reader.

 Can you write us a brief article that will convince me of its benefits,
 and the error of my ways please. There's no Borders where I live, and
 Amazon does not deliver to Africa, so I don't have the benefit of your
 book.

First, Borders is gone :)

http://online.wsj.com/article/SB10001424052702303661904576454353768550280.html

Second, auto is probably the best part of D besides slices.

The main reason auto is useful is it consolidates all type declarations  
into one location.

Take this (arguably arbitrary) pseudocode:

uint i = 5;
uint j = i;
uint k = j;
uint l = k;

If I want to make this code 64-bit aware, I need to change all 4 lines.   
If these lines are scattered throughout the code, I have to play the  
cyclical compiler game, where I change the first one, then compile, change  
the second one, compile, etc.

But compare to:

uint i = 5;
auto j = i;
auto k = j;
auto l = k;

I change one line, and it changes all the types throughout the code  
without me having to do *anything*.

If you step back and look at this from a concept level, the concept of  
auto (in this context) is saying "I want a copy of this value, I don't  
care what the type is".

That power is incredible for a statically typed language.  It almost  
rivals a dynamic typed one.

There is also the DRY T x = new T argument, but I think that's been  
well-covered.

Now, there's one more thing -- auto returns.  This I find to be necessary  
(for easy-to-write generic code), but in fact, *more* confusing than  
declaring the return type.  Simply because the user of your function has  
to do some testing of the introspection (i.e. pragma(msg,  
typeof(foo()).stringof) ), or must read the body of your function to  
figure out what's being returned (and that could depend on static ifs,  
more auto-return functions, etc.

If you look for my response to Andrei later I posted a couple days ago,  
I've outlined a solution which could be useful for allowing auto in  
examples, but giving more info for the interested reader.

-Steve

Steve Teale <steve.teale britseyeview.com> writes:

On Mon, 07 Nov 2011 07:17:59 -0500, Steven Schveighoffer wrote:
 uint i = 5;
 uint j = i;
 uint k = j;
 uint l = k;
 
 If I want to make this code 64-bit aware, I need to change all 4 lines.
 If these lines are scattered throughout the code, I have to play the
 cyclical compiler game, where I change the first one, then compile,
 change the second one, compile, etc.

Steve,

OK, you've uncovered a stark example of my ignorance there. The Types 
documentation does not as far as I can see mention any differences 
between a 32 bit and a 64 bit environment. It says simply that a uint is 
32 bits unsigned.

What is the change that has to be made in your example?

Steve

"Steven Schveighoffer" <schveiguy yahoo.com> writes:

On Mon, 07 Nov 2011 11:51:36 -0500, Steve Teale  
<steve.teale britseyeview.com> wrote:

 On Mon, 07 Nov 2011 07:17:59 -0500, Steven Schveighoffer wrote:
 uint i = 5;
 uint j = i;
 uint k = j;
 uint l = k;

 If I want to make this code 64-bit aware, I need to change all 4 lines.
 If these lines are scattered throughout the code, I have to play the
 cyclical compiler game, where I change the first one, then compile,
 change the second one, compile, etc.

 Steve,

 OK, you've uncovered a stark example of my ignorance there. The Types
 documentation does not as far as I can see mention any differences
 between a 32 bit and a 64 bit environment. It says simply that a uint is
 32 bits unsigned.

 What is the change that has to be made in your example?

Sorry, that is my fault.  My example was too devoid of context :)

Try this instead:

int[] arr;

uint i = arr.length;
...

i.e. the change that should be made is uint => size_t.

-Steve

"Jonathan M Davis" <jmdavisProg gmx.com> writes:

On Monday, November 07, 2011 08:55 Steven Schveighoffer wrote:
 On Mon, 07 Nov 2011 11:51:36 -0500, Steve Teale
 
 <steve.teale britseyeview.com> wrote:
 On Mon, 07 Nov 2011 07:17:59 -0500, Steven Schveighoffer wrote:
 uint i = 5;
 uint j = i;
 uint k = j;
 uint l = k;
 
 If I want to make this code 64-bit aware, I need to change all 4 lines.
 If these lines are scattered throughout the code, I have to play the
 cyclical compiler game, where I change the first one, then compile,
 change the second one, compile, etc.

 
 Steve,
 
 OK, you've uncovered a stark example of my ignorance there. The Types
 documentation does not as far as I can see mention any differences
 between a 32 bit and a 64 bit environment. It says simply that a uint is
 32 bits unsigned.
 
 What is the change that has to be made in your example?

 
 Sorry, that is my fault. My example was too devoid of context :)
 
 Try this instead:
 
 int[] arr;
 
 uint i = arr.length;
 ...
 
 i.e. the change that should be made is uint => size_t.

Yeah, all of those examples would be typed to int. size_t is actually a prime 
example of when you actually need to use the type. The length property on an 
array is one of the few cases where the type will be inferred as size_t.

- Jonathan M Davis

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 07.11.2011, 18:36 Uhr, schrieb Jonathan M Davis <jmdavisProg gmx.com>=
:

 On Monday, November 07, 2011 08:55 Steven Schveighoffer wrote:
 On Mon, 07 Nov 2011 11:51:36 -0500, Steve Teale

 <steve.teale britseyeview.com> wrote:
 On Mon, 07 Nov 2011 07:17:59 -0500, Steven Schveighoffer wrote:
 uint i =3D 5;
 uint j =3D i;
 uint k =3D j;
 uint l =3D k;

 If I want to make this code 64-bit aware, I need to change all 4  =




 lines.
 If these lines are scattered throughout the code, I have to play t=




he
 cyclical compiler game, where I change the first one, then compile=




,
 change the second one, compile, etc.

 Steve,

 OK, you've uncovered a stark example of my ignorance there. The Typ=



es
 documentation does not as far as I can see mention any differences
 between a 32 bit and a 64 bit environment. It says simply that a ui=



nt  =

 is
 32 bits unsigned.

 What is the change that has to be made in your example?

 Sorry, that is my fault. My example was too devoid of context :)

 Try this instead:

 int[] arr;

 uint i =3D arr.length;
 ...

 i.e. the change that should be made is uint =3D> size_t.

 Yeah, all of those examples would be typed to int. size_t is actually =

a  =

 prime
 example of when you actually need to use the type. The length property=

  =

 on an
 array is one of the few cases where the type will be inferred as size_=

t.
 - Jonathan M Davis

After some hacking into the keyboard layout file, I now use the alias =E2=
=84=95  =

(the mathematical symbol for the non-negative integral number) everywher=
e  =

instead of the ugly size_t. It is even shorter than 'auto'.

=E2=84=95 i =3D 5;
=E2=84=95 j =3D i;
=E2=84=95 k =3D j;
=E2=84=95 l =3D k;

;)

Jonathan M Davis <jmdavisProg gmx.com> writes:

On Tuesday, November 08, 2011 17:25:57 Marco Leise wrote:
 After some hacking into the keyboard layout file, I now use the alias=

 =E2=84=95
 (the mathematical symbol for the non-negative integral number) everyw=

here
 instead of the ugly size_t. It is even shorter than 'auto'.
=20
 =E2=84=95 i =3D 5;
 =E2=84=95 j =3D i;
 =E2=84=95 k =3D j;
 =E2=84=95 l =3D k;
=20
 ;)

LOL. And no one but you will have any idea what your code is doing. It =
_is_=20
kind of cool to see unicode like that in D, but that's _really_ bad pra=
ctice=20
if you intend anyone else to ever read your code. If it's just for you,=
 then=20
you obviously can do whatever you want, but size_t is the correct name =
and=20
what others are going to expect if they ever read your code.

- Jonathan M Davis

Tobias Pankrath <tobias pankrath.net> writes:

Jonathan M Davis wrote:

 On Tuesday, November 08, 2011 17:25:57 Marco Leise wrote:
 After some hacking into the keyboard layout file, I now use the alias ℕ
 (the mathematical symbol for the non-negative integral number) everywhere
 instead of the ugly size_t. It is even shorter than 'auto'.
 
 ℕ i = 5;
 ℕ j = i;
 ℕ k = j;
 ℕ l = k;
 
 ;)


No need for hacking, if you use www.neo-layout.org. I've learned it last 
year. Biggest improvement of my human-computer interface for years.

 but that's really bad practice 
 if you intend anyone else to ever read your code. If it's just for you, 

then you obviously can do whatever you want, but size_t is the correct name 
 and  what others are going to expect if they ever read your code.

Only because it's an alias for an build-in type, that is unnecessary. You 
could say the same thing about every other typedef. The reason, why this is 
bad practice is, that almost no one can easily write that type with a QWERTY
keyboard.

"Jonathan M Davis" <jmdavisProg gmx.com> writes:

On Tuesday, November 08, 2011 10:43 Tobias Pankrath wrote:
 Jonathan M Davis wrote:
 On Tuesday, November 08, 2011 17:25:57 Marco Leise wrote:
 After some hacking into the keyboard layout file, I now use the alias ℕ
 (the mathematical symbol for the non-negative integral number)
 everywhere instead of the ugly size_t. It is even shorter than 'auto'.
 
 ℕ i = 5;
 ℕ j = i;
 ℕ k = j;
 ℕ l = k;
 
 ;)


 
 No need for hacking, if you use www.neo-layout.org. I've learned it last
 year. Biggest improvement of my human-computer interface for years.
 
 but that's really bad practice
 if you intend anyone else to ever read your code. If it's just for you,

 
 then you obviously can do whatever you want, but size_t is the correct name
 
 and what others are going to expect if they ever read your code.

 
 Only because it's an alias for an build-in type, that is unnecessary. You
 could say the same thing about every other typedef. The reason, why this is
 bad practice is, that almost no one can easily write that type with a
 QWERTY keyboard.

It's bad practice on both counts. Creating an unnecessary alias (especially 
for a built-in type) just serves to obfuscate code and confuse other 
programmers. Regardless of the name chosen, it shouldn't be done. And as cool 
as it may be to be able to use unicode in a .d file, unicode characters are 
not typeable on most keyboards, so using unicode characters for anything 
outside of strings is generally a bad idea.

- Jonathan M Davis

Tobias Pankrath <tobias pankrath.net> writes:

Jonathan M Davis wrote:

 It's bad practice on both counts. Creating an unnecessary alias
 (especially for a built-in type) just serves to obfuscate code and confuse
 other programmers. Regardless of the name chosen, it shouldn't be done.
 And as cool as it may be to be able to use unicode in a .d file, unicode
 characters are not typeable on most keyboards, so using unicode characters
 for anything outside of strings is generally a bad idea.
 

Exactly what I mean. My point was, that unicode names wouldn't be bad 
practice if everyone could easily write them, which is not the case :-( 

I fully agree on the "no alias of build-ins" thing.

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 08.11.2011, 20:28 Uhr, schrieb Tobias Pankrath <tobias pankrath.net>:

 Jonathan M Davis wrote:

 It's bad practice on both counts. Creating an unnecessary alias
 (especially for a built-in type) just serves to obfuscate code and  
 confuse
 other programmers. Regardless of the name chosen, it shouldn't be done.
 And as cool as it may be to be able to use unicode in a .d file, unicode
 characters are not typeable on most keyboards, so using unicode  
 characters
 for anything outside of strings is generally a bad idea.

 Exactly what I mean. My point was, that unicode names wouldn't be bad
 practice if everyone could easily write them, which is not the case :-(

 I fully agree on the "no alias of build-ins" thing.

Nah, DDOC can help with the obfuscation:  
http://img805.imageshack.us/img805/5646/hinton.png
I would not use this in anything that is supposed to end up as a library  
for anyone to use.
Maybe in an "open-source" project where I don't actually want others to  
mess with my code, but use GitHub's free services. ;)

=?utf-8?Q?Simen_Kj=C3=A6r=C3=A5s?= <simen.kjaras gmail.com> writes:

On Tue, 08 Nov 2011 17:53:06 +0100, Jonathan M Davis <jmdavisProg gmx.co=
m>  =

wrote:

 On Tuesday, November 08, 2011 17:25:57 Marco Leise wrote:
 After some hacking into the keyboard layout file, I now use the alias=


 =E2=84=95
 (the mathematical symbol for the non-negative integral number)  =


 everywhere
 instead of the ugly size_t. It is even shorter than 'auto'.

 =E2=84=95 i =3D 5;
 =E2=84=95 j =3D i;
 =E2=84=95 k =3D j;
 =E2=84=95 l =3D k;

 ;)

 LOL. And no one but you will have any idea what your code is doing. It=

  =

 _is_
 kind of cool to see unicode like that in D, but that's _really_ bad  =

 practice
 if you intend anyone else to ever read your code. If it's just for you=

,  =

 then
 you obviously can do whatever you want, but size_t is the correct name=

  =

 and
 what others are going to expect if they ever read your code.

Also, =E2=84=95 would more correctly be a BigUInt, as it has no upper bo=
und.

Manu <turkeyman gmail.com> writes:

On 5 November 2011 22:14, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org
 wrote:

 On 11/5/11 3:02 PM, bearophile wrote:

 Andrei Alexandrescu:

  If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.

 Sample code should mimic real code. If real code would use auto,
 sample code should use auto.

 D programmers are probably able to learn to use auto later, because
 it's handy, it's an attractor. On the other hand one of the main
 purposes of the online documentation is to be as clear as possible. D
 written by newbies is not the same D written by D experts. But
 documentation must be written for D newbies too, because they are
 ones that have more need of documentation. The code written in the
 thousands of examples in the very good Pascal/Delphi docs was written
 in a clear style that is not the same compact style an expert Delphi
 programmer writes code. So I'd like D docs to avoid auto when the
 types are not very clear. The purpose of the docs is not to shows
 examples of idiomatic D code written by experts.

 Patronizing one's reader is a common trap.


There's nothing patronising about printing the types clearly.

As a D new comer myself, I DEFINITELY want to see the types associated with
function documentation in such examples. It re-enforces my memory, and also
informs me if I don't know without wasting my time looking it up.
It might even be nice if that doc also hyperlinked to the type and function
references themselves... save me more time looking this stuff up.

Walter Bright <newshound2 digitalmars.com> writes:

On 11/5/2011 12:49 PM, Andrei Alexandrescu wrote:
 On 11/5/11 1:48 PM, Walter Bright wrote:
 I agree.

 It's tricky. One simple fact that's been verified again and again is that
 documentation examples tend to be used a lot. They effectively are powerful
 style influencers for people learning the language.

 If we avoid "auto" in documentation examples but we do use it in everyday code,
 we effectively foster a style that's foreign and non-idiomatic to newcomers.

 Sample code should mimic real code. If real code would use auto, sample code
 should use auto.

Also a great point. The issue I have with auto in the library doc is I want to 
know what the function is returning. For example, is it a range or an int?

"Vladimir Panteleev" <vladimir thecybershadow.net> writes:

On Sat, 05 Nov 2011 21:49:11 +0200, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 It's tricky. One simple fact that's been verified again and again is  
 that documentation examples tend to be used a lot. They effectively are  
 powerful style influencers for people learning the language.

 If we avoid "auto" in documentation examples but we do use it in  
 everyday code, we effectively foster a style that's foreign and  
 non-idiomatic to newcomers.

 Sample code should mimic real code. If real code would use auto, sample  
 code should use auto.

I find that I frequently need to look up the return type of a function  
when the example doesn't mention it. One could argue that documentation  
examples shouldn't be considered as "sample code" and thus expected to be  
idiomatic, because they're highly contextual. Either way, a possible  
compromise could be to use the return type when it's highly likely that  
the user will want to use the type in their programs (class field or  
global variable declarations). For example, time values occur frequently  
as non-local variables, while the results of functional programming  
functions (map/reduce/etc.) do not.

-- 
Best regards,
  Vladimir                            mailto:vladimir thecybershadow.net

Dejan Lekic <dejan.lekic gmail.com> writes:

On Sat, 05 Nov 2011 14:49:11 -0500, Andrei Alexandrescu wrote:

 
 Sample code should mimic real code. If real code would use auto, sample
 code should use auto.
 

It is tricky because people have different styles... I try to avoid auto 
as much as possible because I find myself wasting time trying to find out 
what the type actually is. Even in the simplest case - when you see auto, 
you must always look right and try to find what the type is. However, 
when you see <type> <name>, you know immediately what type the <name> 
is... I believe it saves me (and whoever is reading my code) time in the 
long run. I do not mind extra typing. :)

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:

On 11/5/11 5:41 PM, Dejan Lekic wrote:
 On Sat, 05 Nov 2011 14:49:11 -0500, Andrei Alexandrescu wrote:

 Sample code should mimic real code. If real code would use auto, sample
 code should use auto.

 It is tricky because people have different styles... I try to avoid auto
 as much as possible because I find myself wasting time trying to find out
 what the type actually is. Even in the simplest case - when you see auto,
 you must always look right and try to find what the type is. However,
 when you see<type>  <name>, you know immediately what type the<name>
 is... I believe it saves me (and whoever is reading my code) time in the
 long run. I do not mind extra typing. :)

Most everyone agrees that sometimes specifying a type, even if 
redundant, is helpful. There are people who think those cases form all 
or a majority of all instances (and hence auto should be avoided), but I 
have reasons to believe they're a minority.

Andrei

dsimcha <dsimcha yahoo.com> writes:

On 11/5/2011 6:48 PM, Andrei Alexandrescu wrote:
 Most everyone agrees that sometimes specifying a type, even if
 redundant, is helpful. There are people who think those cases form all
 or a majority of all instances (and hence auto should be avoided), but I
 have reasons to believe they're a minority.

 Andrei

I tend to agree with Andrei here.  I'm a bit biased, though, because 
before I started using D most of my experience was in dynamic, 
duck-typed languages.  To me, the nominal type of something doesn't 
really mean much.  Occasionally it's useful to see a type explicitly 
specified when there's a specific reason why it needs to be emphasized 
for clarity.  On the other hand, languages like Python, Ruby, PHP and 
Perl argue very strongly that we could move even further away from 
explicit type declarations and still have a usable language.

"Steven Schveighoffer" <schveiguy yahoo.com> writes:

On Sat, 05 Nov 2011 15:49:11 -0400, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 On 11/5/11 1:48 PM, Walter Bright wrote:
 On 11/5/2011 10:42 AM, Steve Teale wrote:
 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

 Now I can understand that when the RHS is some obscure template, whose
 type might not be immediately obvious, the user should possibly be
 encouraged to RTFM. But if the outcome is deterministic I just have the
 feeling that documentation should provide information rather than  
 hiding
 it.

 OK, in Jonathan's example, this is preceded by a sentence that says  
 that
 the result is a SysTime. But the auto made me forget, and wonder what  
 it
 was, rather than reinforcing the preceding sentence.

 I realize that this is probably a trivial point, but at the same time,  
 in
 documentation, clarity is wonderful.

 I agree.

 It's tricky. One simple fact that's been verified again and again is  
 that documentation examples tend to be used a lot. They effectively are  
 powerful style influencers for people learning the language.

 If we avoid "auto" in documentation examples but we do use it in  
 everyday code, we effectively foster a style that's foreign and  
 non-idiomatic to newcomers.

 Sample code should mimic real code. If real code would use auto, sample  
 code should use auto.

The compiler's generating the docs, and I know that it's not actually  
compiling the examples, but here's my suggestion (if it's possible):

1. The compiler determine what the actual "auto" type would be.
2. If the user hovers the mouse over auto, display a tooltip with the  
auto-determined name
3. There should be a button to turn all autos into their normal types.

Sould feasible?

As a bonus, it would actually verify the examples are valid code (even if  
they aren't semantically valid) ;)

-Steve

Andrej Mitrovic <andrej.mitrovich gmail.com> writes:

On 11/6/11, Steven Schveighoffer <schveiguy yahoo.com> wrote:
 2. If the user hovers the mouse over auto, display a tooltip with the
 auto-determined name

That would scare people away when they see the name of a sophisticated
template instantiation. :)

"Steven Schveighoffer" <schveiguy yahoo.com> writes:

On Sat, 05 Nov 2011 20:53:25 -0400, Andrej Mitrovic  
<andrej.mitrovich gmail.com> wrote:

 On 11/6/11, Steven Schveighoffer <schveiguy yahoo.com> wrote:
 2. If the user hovers the mouse over auto, display a tooltip with the
 auto-determined name

 That would scare people away when they see the name of a sophisticated
 template instantiation. :)

I would think the opposite.

"whoa!  auto makes it so I don't have to type all that junk?  Awesome!"

-Steve

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 07.11.2011, 13:18 Uhr, schrieb Steven Schveighoffer  
<schveiguy yahoo.com>:

 On Sat, 05 Nov 2011 20:53:25 -0400, Andrej Mitrovic  
 <andrej.mitrovich gmail.com> wrote:

 On 11/6/11, Steven Schveighoffer <schveiguy yahoo.com> wrote:
 2. If the user hovers the mouse over auto, display a tooltip with the
 auto-determined name

 That would scare people away when they see the name of a sophisticated
 template instantiation. :)

 I would think the opposite.

 "whoa!  auto makes it so I don't have to type all that junk?  Awesome!"

 -Steve

Or "Omg! D's templates generates all this junk that can only be coped with  
using auto?", hehe.
I remember when I first looked into std.algorithm _without_ any functional  
programming background or reading Andrei's book. It was absolutely  
incomprehensible to me, what these functions like 'filter' could return or  
how I can make use of it. I wanted to put an array into it and get back a  
filtered array. I imagined that the return value must be some obscure  
language internal called a 'Result' and found no other way to use it  
except for wrapping any functions from std.algorithm in another call to  
array(...). Only recently I understood enough of CTFE to recognize that  
the return values are still conventional structs offering an implicit  
interface and no black magic. Now I quite like what is possible with - for  
example - map in one line of code.

torhu <no spam.invalid> writes:

On 05.11.2011 20:49, Andrei Alexandrescu wrote:
 On 11/5/11 1:48 PM, Walter Bright wrote:
  On 11/5/2011 10:42 AM, Steve Teale wrote:
  There's a growing tendency in Phobos documentation to use auto.

  auto now = Clock.currTime();

  Now I can understand that when the RHS is some obscure template, whose
  type might not be immediately obvious, the user should possibly be
  encouraged to RTFM. But if the outcome is deterministic I just have the
  feeling that documentation should provide information rather than hiding
  it.

  OK, in Jonathan's example, this is preceded by a sentence that says that
  the result is a SysTime. But the auto made me forget, and wonder what it
  was, rather than reinforcing the preceding sentence.

  I realize that this is probably a trivial point, but at the same time, in
  documentation, clarity is wonderful.

  I agree.

 It's tricky. One simple fact that's been verified again and again is
 that documentation examples tend to be used a lot. They effectively are
 powerful style influencers for people learning the language.

 If we avoid "auto" in documentation examples but we do use it in
 everyday code, we effectively foster a style that's foreign and
 non-idiomatic to newcomers.

 Sample code should mimic real code. If real code would use auto, sample
 code should use auto.

I probably wouldn't use auto in that case. I like having the type 
explicit, as it saves me from having to spend any effort on remembering 
what it was. Sometimes the type is too complicated, can vary, or is 
already mentioned on the right hand side of the expression.  Then often 
find myself using auto.

In short, I feel that in this example, auto takes away clarity without 
adding anything that makes it a net gain.

=?UTF-8?B?QWxleCBSw7hubmUgUGV0ZXJzZW4=?= <xtzgzorex gmail.com> writes:

On 05-11-2011 18:42, Steve Teale wrote:
 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

 Now I can understand that when the RHS is some obscure template, whose
 type might not be immediately obvious, the user should possibly be
 encouraged to RTFM. But if the outcome is deterministic I just have the
 feeling that documentation should provide information rather than hiding
 it.

 OK, in Jonathan's example, this is preceded by a sentence that says that
 the result is a SysTime. But the auto made me forget, and wonder what it
 was, rather than reinforcing the preceding sentence.

 I realize that this is probably a trivial point, but at the same time, in
 documentation, clarity is wonderful.

 Steve

I agree on this. auto is useful when writing code; less so when reading 
it (especially if RHS is not a 'new' expression).

- Alex

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 05.11.2011, 18:42 Uhr, schrieb Steve Teale  
<steve.teale britseyeview.com>:

 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

 Now I can understand that when the RHS is some obscure template, whose
 type might not be immediately obvious, the user should possibly be
 encouraged to RTFM. But if the outcome is deterministic I just have the
 feeling that documentation should provide information rather than hiding
 it.

 OK, in Jonathan's example, this is preceded by a sentence that says that
 the result is a SysTime. But the auto made me forget, and wonder what it
 was, rather than reinforcing the preceding sentence.

 I realize that this is probably a trivial point, but at the same time, in
 documentation, clarity is wonderful.

 Steve

+1

And DDOC, IDEs and other tools should print/know about the inferred type  
of auto and the examples should use the actual type, unless it is for  
example some Range type or obvious from the right hand side of an  
assignment. This is also what I try to do in my own code, because auto  
keeps confusing me and DDT doesn't know how to infer the type yet :p

Jesse Phillips <jessekphillips+d gmail.com> writes:

On Sat, 05 Nov 2011 17:42:59 +0000, Steve Teale wrote:

 There's a growing tendency in Phobos documentation to use auto.
 
 auto now = Clock.currTime();
 
 Now I can understand that when the RHS is some obscure template, whose
 type might not be immediately obvious, the user should possibly be
 encouraged to RTFM. But if the outcome is deterministic I just have the
 feeling that documentation should provide information rather than hiding
 it.
 
 OK, in Jonathan's example, this is preceded by a sentence that says that
 the result is a SysTime. But the auto made me forget, and wonder what it
 was, rather than reinforcing the preceding sentence.
 
 I realize that this is probably a trivial point, but at the same time,
 in documentation, clarity is wonderful.
 
 Steve

I find it interesting that the exception is given to the "obscure 
template, whose type might not be immediately obvious." For one thing 
such types are fairly common in Phobos. For another, doesn't that just 
mean that once the type gets complicated you don't care anymore and 
instead just care about what you can do with what is returned?

I think examples should make use of auto, unless the result isn't going 
to be used in the example. But more importantly I think all non-template 
functions which use auto return types should have DDoc show the specific 
type.

Trass3r <un known.com> writes:

 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

This is not restricted to documentation.
auto makes people lazy and they tend to (ab)use it freakin everywhere in  
code.
It was invented and intended for things like C++'s iterators which are
tedious to write down, not for saving 2 keystrokes.

Trass3r <un known.com> writes:

 There's a growing tendency in Phobos documentation to use auto.

 auto now = Clock.currTime();

This is not restricted to documentation.
auto makes people lazy and they tend to (ab)use it everywhere in code.
It was invented and intended for things like C++'s iterators where the  
resulting type is clear but tedious to write down, not for saving 2  
keystrokes.

Kagamin <spam here.lot> writes:

Steve Teale Wrote:

 There's a growing tendency in Phobos documentation to use auto.
 
 auto now = Clock.currTime();
 
 Now I can understand that when the RHS is some obscure template, whose 
 type might not be immediately obvious, the user should possibly be 
 encouraged to RTFM. But if the outcome is deterministic I just have the 
 feeling that documentation should provide information rather than hiding 
 it.
 
 OK, in Jonathan's example, this is preceded by a sentence that says that 
 the result is a SysTime. But the auto made me forget, and wonder what it 
 was, rather than reinforcing the preceding sentence.

All you need to know is that it's a time, and you don't need to know anything
else. The design makes sure the type supports idiomatic operations, and the
type system makes sure the operations are ok. The docs also demonstrate how
easy it is to write D: you don't need to know the type name and everything
still works.

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 07.11.2011, 14:09 Uhr, schrieb Kagamin <spam here.lot>:

 All you need to know is that it's a time, and you don't need to know  
 anything else. The design makes sure the type supports idiomatic  
 operations, and the type system makes sure the operations are ok. The  
 docs also demonstrate how easy it is to write D: you don't need to know  
 the type name and everything still works.

It takes a while for a person to build up so much faith into the library.  
And after all there are different 'times' in the wild, like file times,  
local/UTC time, dates without times, times without dates, hardware tick  
counts. I'm not sure I can use the current system time and subtract a  
TickDuration from it. Does this work, or only as long as you don't cross  
module boundaries? It may be a minor issue or personal taste, but I also  
like to be able to jump to the declaration of a type by ctrl-clicking on  
its name or get auto-completion that - despite its name - works only with  
variables not declared as auto for now in the most sophisticated D2 IDE on  
Linux. And since often you only have to type two or three letters of a  
type name for it to be auto-completed, it isn't even often a time saver to  
write auto. I accept the "easier to refactor the used type" argument  
though :)

"Jonathan M Davis" <jmdavisProg gmx.com> writes:

On Tuesday, November 08, 2011 09:03 Marco Leise wrote:
 Am 07.11.2011, 14:09 Uhr, schrieb Kagamin <spam here.lot>:
 All you need to know is that it's a time, and you don't need to know
 anything else. The design makes sure the type supports idiomatic
 operations, and the type system makes sure the operations are ok. The
 docs also demonstrate how easy it is to write D: you don't need to know
 the type name and everything still works.

 
 It takes a while for a person to build up so much faith into the library.
 And after all there are different 'times' in the wild, like file times,
 local/UTC time, dates without times, times without dates, hardware tick
 counts. I'm not sure I can use the current system time and subtract a
 TickDuration from it. Does this work, or only as long as you don't cross
 module boundaries?

std.datetime publicly imports core.time, and both a Duration and a 
TickDuration can be added or subtracted from the various time point types 
(including SysTime). If it didn't though, you could just cast it to Duration 
(or even better, use std.conv.to do that) and add or subtract that. Module 
boundaries have nothing to do with it, and I don't see how they could. If 
std.datetime uses something, it imports it. If it doesn't publicly import it, 
and a function in std.datetime takes it as an argument or returns it, you have 
to import it in your code which uses that function. It's the same with any 
other module.

- Jonathan M Davis

"Marco Leise" <Marco.Leise gmx.de> writes:

Am 08.11.2011, 19:16 Uhr, schrieb Jonathan M Davis <jmdavisProg gmx.com>:

 On Tuesday, November 08, 2011 09:03 Marco Leise wrote:
 Am 07.11.2011, 14:09 Uhr, schrieb Kagamin <spam here.lot>:
 All you need to know is that it's a time, and you don't need to know
 anything else. The design makes sure the type supports idiomatic
 operations, and the type system makes sure the operations are ok. The
 docs also demonstrate how easy it is to write D: you don't need to  

 know
 the type name and everything still works.

 It takes a while for a person to build up so much faith into the  
 library.
 And after all there are different 'times' in the wild, like file times,
 local/UTC time, dates without times, times without dates, hardware tick
 counts. I'm not sure I can use the current system time and subtract a
 TickDuration from it. Does this work, or only as long as you don't cross
 module boundaries?

 std.datetime publicly imports core.time, and both a Duration and a
 TickDuration can be added or subtracted from the various time point types
 (including SysTime). If it didn't though, you could just cast it to  
 Duration
 (or even better, use std.conv.to do that) and add or subtract that.  
 Module
 boundaries have nothing to do with it, and I don't see how they could. If
 std.datetime uses something, it imports it. If it doesn't publicly  
 import it,
 and a function in std.datetime takes it as an argument or returns it,  
 you have
 to import it in your code which uses that function. It's the same with  
 any
 other module.

 - Jonathan M Davis

With module boundaries I meant that it could have been that modules work  
only with stuff defined inside of them. I'm really surprised that any time  
or duration type works with all the others. In other words I wouldn't even  
have *tried* to do that and instead rolled my own conversion code. Sorry  
for the ignorance and so on...

- Marco

Jonathan M Davis <jmdavisProg gmx.com> writes:

On Tuesday, November 08, 2011 21:09:00 Marco Leise wrote:
 With module boundaries I meant that it could have been that modules work
 only with stuff defined inside of them. I'm really surprised that any time
 or duration type works with all the others. In other words I wouldn't even
 have *tried* to do that and instead rolled my own conversion code. Sorry
 for the ignorance and so on...

If you look at the API, Duration and TickDuration can clearly cast to one 
another and can intermix with binary operators. It does look like it's not as 
clear in std.datetime though that both types of durations work with the time 
point types, since the docs just say duration - not Duration or TickDuration - 
so I should probably make them clearer. But the date/time stuff is quite 
interoperable in general. It was designed to work together. You shouldn't need 
to write any conversion code yourself.

- Jonathan M Davis