View mode: basic / threaded / horizontal-split · Log in · Help
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
Yes
---
Oleg
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
Looks good, though one thing annoys me as always throughout the D docs,
liberal use of auto can make them very difficult to understand.

auto result = hash.finish();

>From the examples where this appears, I have absolutely no idea what
'result' could possibly be and what I can do with it, and you're forcing me
to go and dig further for that information (waste of time).
Surely there would be no harm in just writing the type there for clarity?

<rant>
I'd personally like to see auto abolished, or at least heavily discouraged
for the sake of clarity from code examples throughout the docs. I'm
constantly having to chase up what auto's may resolve to when reading
examples >_<
You may argue this demonstrated un-idiomatic code, and my trouble is due to
inexperience; I ask, who is most likely to be reading docs?


On 26 August 2012 04:54, Oleg Kuporosov <Oleg.Kuporosov@gmail.com> wrote:

>
> Yes
> ---
> Oleg
>
>
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
"Manu" <turkeyman@gmail.com> wrote in message news:mailman.1410.1345976415.31962.digitalmars-d@puremagic.com...
Looks good, though one thing annoys me as always throughout the D docs, liberal use of auto can make them very difficult to understand. 
auto result = hash.finish();From the examples where this appears, I have absolutely no idea what 'result' could possibly be and what I can do with it, and you're forcing me to go and dig further for that information (waste of time).
Surely there would be no harm in just writing the type there for clarity?
<rant>
I'd personally like to see auto abolished, or at least heavily discouraged for the sake of clarity from code examples throughout the docs. I'm constantly having to chase up what auto's may resolve to when reading examples >_<
You may argue this demonstrated un-idiomatic code, and my trouble is due to inexperience; I ask, who is most likely to be reading docs?



On 26 August 2012 04:54, Oleg Kuporosov <Oleg.Kuporosov@gmail.com> wrote:


 Yes
 ---
 Oleg




+1.

The documentation should be there for clarity.

-=mike=-
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
On Sunday, 26 August 2012 at 10:32:37 UTC, Mike James wrote:
>
> "Manu" <turkeyman@gmail.com> wrote in message 
> news:mailman.1410.1345976415.31962.digitalmars-d@puremagic.com...
> Looks good, though one thing annoys me as always throughout the 
> D docs, liberal use of auto can make them very difficult to 
> understand.
> auto result = hash.finish();From the examples where this 
> appears, I have absolutely no idea what 'result' could possibly 
> be and what I can do with it, and you're forcing me to go and 
> dig further for that information (waste of time).
> Surely there would be no harm in just writing the type there 
> for clarity?
> <rant>
> I'd personally like to see auto abolished, or at least heavily 
> discouraged for the sake of clarity from code examples 
> throughout the docs. I'm constantly having to chase up what 
> auto's may resolve to when reading examples >_<
> You may argue this demonstrated un-idiomatic code, and my 
> trouble is due to inexperience; I ask, who is most likely to be 
> reading docs?
>
>
>
> On 26 August 2012 04:54, Oleg Kuporosov 
> <Oleg.Kuporosov@gmail.com> wrote:
>
>
>   Yes
>   ---
>   Oleg
>
>
>
>
> +1.
>
> The documentation should be there for clarity.
>
> -=mike=-

+2
As a very inexperienced D user, I find the use of auto in the
documentation frustrating too.

Cheers,

Craig
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
Am Sun, 26 Aug 2012 13:19:35 +0300
schrieb Manu <turkeyman@gmail.com>:

> Looks good, though one thing annoys me as always throughout the D
> docs, liberal use of auto can make them very difficult to understand.
> 
> auto result = hash.finish();
> 
> >From the examples where this appears, I have absolutely no idea what
> 'result' could possibly be and what I can do with it, and you're
> forcing me to go and dig further for that information (waste of time).
> Surely there would be no harm in just writing the type there for
> clarity?
> 
> <rant>
> I'd personally like to see auto abolished, or at least heavily
> discouraged for the sake of clarity from code examples throughout the
> docs. I'm constantly having to chase up what auto's may resolve to
> when reading examples >_<
> You may argue this demonstrated un-idiomatic code, and my trouble is
> due to inexperience; I ask, who is most likely to be reading docs?
> 

OK, I'll fix this if std.digest is accepted into phobos.

However, in this example auto is not just used for convenience, it has
an actual use case:

As documented here
http://dl.dropbox.com/u/24218791/d/phobos/std_digest_digest.html#ExampleDigest
(finish method) the type returned by finish can differ between different
hash implementations. It's always a static array of ubyte, but for crc
it's ubyte[4] for sha1 it's ubyte[20] and for md5 it's ubyte[16]. So
in templated methods, auto is more generic than hardcoding a type. The
equivalent to auto is using digestType!Digest, so

auto result = hash.finish();
digestType!(typeof(hash)) result = hash.finish();

are equivalent. But 

ubyte[4] result = hash.finish();

does only work if hash is a CRC32 digest. It does not work for md5, sha1
digests, etc.

But I agree that examples are easier to read without auto, so I'll
change them to use the explicit type where possible.
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
On 8/26/12 8:35 AM, Craig Dillabaugh wrote:
> On Sunday, 26 August 2012 at 10:32:37 UTC, Mike James wrote:
> +2
> As a very inexperienced D user, I find the use of auto in the
> documentation frustrating too.
>
> Cheers,
>
> Craig

I'm torn on this. The arguments make sense; on the other hand, people 
will in all likelihood write their own code in the style promoted by the 
doc examples.

How about this - use auto for code samples, but not for documenting 
function return types (except Voldemort)?


Andrei
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
Andrei Alexandrescu:

> I'm torn on this. The arguments make sense; on the other hand, 
> people will in all likelihood write their own code in the style 
> promoted by the doc examples.
>
> How about this - use auto for code samples, but not for 
> documenting function return types (except Voldemort)?

Generally I'd like the documentation examples to not use auto, 
because this makes the examples more clear and less easy to 
misunderstand.

Programmers are lazy, so I think D programmers learn quickly how 
much handy 'auto' is. So I think the risk you refer to of them 
not using auto in their code is low.

Teachers know that usually you have to teach people the less 
handy things, because students learn the lazy things more 
quickly. Example: in D.learn someone was saying that adding the 
immutable/const/pure/nothrow annotations is boring.

In my code I use often auto for variable defined inside 
functions, but usually I write the real return type of functions, 
because this helps me understand better the code I am working 
one, it's more self-documenting. Even in Haskell, where there is 
a powerful global type inferencer, you usually write down the 
types of inputs and outputs of functions, for similar reasons.

Bye,
bearophile
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
On 8/22/12 8:36 AM, Dmitry Olshansky wrote:
> The discussion around new unified API for digest hash functions has
> subdued, just in time as the review period has ended.
>
> The voting for std.digest package starts today and ends on 29 August.
>
> Rules are simple: reply in this thread with definite "YES" or "NO" on
> whether this package should go into Phobos. Including descriptive short
> notes is appreciated (esp. the NO ones).
>
>
> Latest locations of docs and source:
>
> Code: (location changed!)
> https://github.com/jpf91/phobos/tree/newHash/std/digest
> https://github.com/jpf91/phobos/compare/master...newHash
>
> Docs: (location changed!)
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_digest.html
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_md.html
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_sha.html
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_crc.html

I couldn't make time for a review during the window, apologies. 
Nevertheless I'd like to make a pass in hope that a few issues can be 
fixed before the code is publicly released.

* No need for start() after default construction in the documentation 
example of CRC32. BTW the documentation of start() suggests that it 
_must_ be called even right after default construction, is that the case?

* In the template interface, no need for void peek(ref ...). Returning 
by value is fine due to the RVO. Same about finish() - just keep the 
functions returning by value.

* This example:

copy(oneMillionRange, &ctx); //Note: You must pass a pointer to copy!

suggests we're doing something wrong. I think a better solution would be 
to have copy() take the target range by "auto ref", and institute this 
passing convention as a general rule for output ranges.

* s/digestType/DigestType/

* s/isDigestable/isDigestible/

* s/startDigest/makeDigest/ - but then again I wonder if requiring 
start() after default construction is needed.

* s/asArray/asStaticArray/. Better yet, we should include this primitive 
in std.conv. Then we get to use to!(ubyte[16])(dynarray).

* The fact that digests aren't unique is trivial by the pigeonhole 
principle, and should not be listed as a bug (the BUGS: tag implies bugs 
in the implementation). It's more interesting if a document can be 
altered to produce a specific digest. If that's what you meant, include 
a link to the appropriate work.

* I don't think the aliases for WrapperDigest!Xyz should be defined. 
Just call that Digest!Xyz and have people use it. It's about as short as 
the aliases.

I vote for inclusion whether or not the points above are addressed, but 
of course it would be great if they were minded before release. 
Apologies for the late review.



Andrei
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
One more thing - for future work, it would be great to have a function a 
la mcookie, see http://linux.about.com/library/cmd/blcmdl1_mcookie.htm.

Andrei
August 26, 2012
Re: Vote for the new std.hash (oops, std.digest)
On Sunday, August 26, 2012 10:14:14 Andrei Alexandrescu wrote:
> How about this - use auto for code samples, but not for documenting
> function return types (except Voldemort)?

I tend to agree with this. If a function needs to return auto in order to be 
reasonable (e.g. it has to because of Voldemort types, it's return type is too 
complicated to _not_ be auto, or its return type varies), then it should 
return auto. Otherwise, we should probably be explicit about the return type. 
However, I think that the code samples should still generally use auto, 
because that's the style that we think should be used in actual code.

- Jonathan M Davis
1 2 3 4
Top | Discussion index | About this forum | D home