Agreeing on doc, and doc contribution style guide, about hash construction; {...}, %(...), hash(), ...

[Juerd]

The problem

The style guide suggests using {} for empty hashes and %() for non-empty hashes. This is inconsistent.

Suggestions

Since {} is considered confusing (although technically it's supposed to be straight forward) with blocks, and empty %() is considered a trap (see rakudo/rakudo#1946), why not just use hash instead? According to jnthn in rakudo/rakudo#1946 (comment) these are a "sure bet".

Suggested: avoid both %() (empty construct is a trap) and {} (possible confusion with blocks) for constructing hashes, and always use hash instead:

my $foo = hash;  # empty hash
my $bar = hash a => 'b', c => 'd';  # non-empty hash

Note: these can be used with or without parentheses. Since that goes for most expressions, that could probably use its own recommendation in the style guide.

[JJ]

El vie., 22 jun. 2018 a las 17:26, Juerd Waalboer (<notifications@github.com>) escribió:

The problem The style guide <https://github.com/perl6/doc/blob/master/writing-docs/STYLEGUIDE.md> suggests using {} for empty hashes and %() for non-empty hashes. This is inconsistent.

It's not inconsistent, it's simply true...

Suggestions Since {} is considered confusing (although technically it's supposed to be straight forward) with blocks, and empty %() is considered a trap (see rakudo/rakudo#1946 <rakudo/rakudo#1946>), why not just use hash instead? According to jnthn in rakudo/rakudo#1946 (comment) <rakudo/rakudo#1946 (comment)> these are a "sure bet". Suggested: avoid both %() (empty construct is a trap) and {} (possible confusion with blocks) for constructing hashes, and always use hash instead: my $foo = hash; # empty hash my $bar = hash a => 'b', c => 'd'; # non-empty hash

Well, this is the style guide. The main problem I see is that if we change it now we might have to change a whole lot of stuff to make it consistent with it. As a matter of fact, this change was made just today and we'll have to go through what is there now to check that we're not initializing using %(). On the other hand, well, this is the style guide. If we don't enforce consistent style in it, such as the one you suggest, I don't know where else could be... I guess I'll have a look and see how much needs to be changed. And anyway, thanks for the suggestion...

[rafaelschipiura]

I'm completely against this. You'll simply not see code like that in the wild. People should be exposed to code somewhat like they will encounter in the ecosystem .

And the {} %(...) distinction is fine and, besides a WAT at first, works just fine in practice.

[Juerd]

You'll simply not see code like that in the wild. People should be exposed to code somewhat like they will encounter in the ecosystem.

Well, is the documentation to be descriptive or prescriptive? The existence of a style guide, and the exclusion of { ... } for hashes because it can be confused with blocks, both strongly suggest prescriptivism. But your argument is based on descriptivism. That's a fair point of view, and maybe the example code in the documentation should indeed look like the code in the ecosystem, but in that case the documentation should not shy away from using { ... } for non-empty hashes.

[Juerd]

By the way, if the style guide does want to prescribe the use of %(...) for creating hashes, instead of hash, the following uses of %(...) with an Iterable of zero items seem to reliably return a new empty hash, unlike empty %():

%(())
%([])
%({})  # lol
%(Empty)
%{}

And then there are%(Nil), %(Any), and even %(Int). I don't know why Any.hash(Any:U:) exists, but it enables a lot of new and confusing ways to create an empty hash. How about %(X::Promise::CauseOnlyValidOnBroken)? ;-)

[Juerd]

There are some interesting performance differences, too!

Benchmark:

use Test;

my $foo;
my %subs := {
    'hash'     => sub { $foo = hash },
    '%(Nil)'   => sub { $foo = %(Nil) },
    '{}'       => sub { $foo = {} },
    '%(Empty)' => sub { $foo = %(Empty) },
    '%({})'    => sub { $foo = %({}) },
    'my %'     => sub { $foo = my % },
};

for %subs.kv -> $k, $v {
    say "Testing $k";
    $foo = "bad";
    $v();
    isa-ok($foo, Hash); 
    is($foo.elems, 0);
};

Bench.new.timethese: 1000000, %subs;

Output:

Testing {}
ok 1 - The object is-a 'Hash'
ok 2 - 
Testing %(Nil)
ok 3 - The object is-a 'Hash'
ok 4 - 
Testing hash
ok 5 - The object is-a 'Hash'
ok 6 - 
Testing my %
ok 7 - The object is-a 'Hash'
ok 8 - 
Testing %({})
ok 9 - The object is-a 'Hash'
ok 10 - 
Testing %(Empty)
ok 11 - The object is-a 'Hash'
ok 12 - 
Benchmark: 
Timing 1000000 iterations of %(Empty), %(Nil), %({}), hash, my %, {}...
  %(Empty): 2.790 wallclock secs (2.797 usr 0.000 sys 2.792 cpu) @ 358382.348/s (n=1000000)
    %(Nil): 1.777 wallclock secs (1.779 usr 0.000 sys 1.779 cpu) @ 562757.602/s (n=1000000)
     %({}): 3.194 wallclock secs (3.194 usr 0.000 sys 3.194 cpu) @ 313061.358/s (n=1000000)
      hash: 0.139 wallclock secs (0.150 usr 0.004 sys 0.154 cpu) @ 7211365.111/s (n=1000000)
      my %: 0.112 wallclock secs (0.110 usr 0.004 sys 0.114 cpu) @ 8926817.946/s (n=1000000)
        {}: 3.263 wallclock secs (3.270 usr 0.000 sys 3.270 cpu) @ 306425.967/s (n=1000000)

Going by the benchmark, &hash is the obvious winner, if you ignore the more obscure my %, which is basically how &hash is implemented. Does anyone understand why it is so much faster, though?

[labster]

You forgot Hash.new and Hash(Empty) and Hash(()). Hash() returns Hash(Any) which is not what we want. TIMTOWTDI!!!

Benchmark (sorted), because it's interesting:

      %( ): 0.102 wallclock secs (0.099 usr 0.000 sys 0.099 cpu) @ 9844166.839/s (n=1000000)
      my %: 0.104 wallclock secs (0.101 usr 0.000 sys 0.101 cpu) @ 9642364.694/s (n=1000000)
      hash: 0.126 wallclock secs (0.136 usr 0.000 sys 0.136 cpu) @ 7956588.851/s (n=1000000)
    %(Nil): 2.418 wallclock secs (2.408 usr 0.003 sys 2.411 cpu) @ 413502.511/s (n=1000000)
  %(Empty): 2.718 wallclock secs (2.720 usr 0.006 sys 2.726 cpu) @ 367961.179/s (n=1000000)
  Any.hash: 2.720 wallclock secs (2.668 usr 0.000 sys 2.657 cpu) @ 367586.650/s (n=1000000)
  Hash.new: 2.793 wallclock secs (2.797 usr 0.021 sys 2.818 cpu) @ 357985.530/s (n=1000000)
        {}: 4.083 wallclock secs (4.065 usr 0.009 sys 4.074 cpu) @ 244889.523/s (n=1000000)
     %({}): 4.150 wallclock secs (4.157 usr 0.007 sys 4.164 cpu) @ 240949.921/s (n=1000000)
  Hash(()): 4.641 wallclock secs (4.639 usr 0.016 sys 4.655 cpu) @ 215458.872/s (n=1000000)
Hash(Empty): 5.027 wallclock secs (4.991 usr 0.003 sys 4.994 cpu) @ 198930.114/s (n=1000000)

[JJ]

El sáb., 23 jun. 2018 a las 5:20, Juerd Waalboer (<notifications@github.com>) escribió:

You'll simply not see code like that in the wild. People should be exposed to code somewhat like they will encounter in the ecosystem. Well, is the documentation to be descriptive <https://en.wikipedia.org/wiki/Linguistic_description> or prescriptive <https://en.wikipedia.org/wiki/Linguistic_prescription>? The existence of a style guide, and the exclusion of { ... } for hashes because it can be confused with blocks, both strongly suggest prescriptivism. But your argument is based on descriptivism. That's a fair point of view, and maybe the example code in the documentation should indeed look like the code in the ecosystem, but in that case the documentation should not shy away from using { ... } for non-empty hashes.

I would say it's prescriptive. In most cases, there's no code "in the wild" to draw from.

[JJ]

El sáb., 23 jun. 2018 a las 7:53, Brent Laabs (<notifications@github.com>) escribió:

You forgot Hash.new and Hash(Empty) and Hash(()). Hash() returns Hash(Any) which is not what we want. TIMTOWTDI!!! Benchmark (sorted), because it's interesting: my %: 0.104 wallclock secs (0.101 usr 0.000 sys 0.101 cpu) @ 9642364.694/s (n=1000000)

I would say this one is a winner. Maybe use this?

[labster]

I just did at talk at TPC about PHP, so I've been talking about that language a bit lately. One of the things I discussed with people afterwards is that PHP is a better language now, because (among other things) you can use square brackets [] for arrays now, instead of the old array(). So let's recommend everyone use hash() in Perl 6? Um, no.

Everything suggested here is a move backwards in readability and style, including my own previous suggestions. %() is a misfeature, but %( ) works, and it is in the same speed area as the entirely unreadable my %.
%( ): 0.102 wallclock secs (0.099 usr 0.000 sys 0.099 cpu) @ 9844166.839/s (n=1000000)
The anonymous variables are not really beginner material IMO, and the anon hash is easily confused with modulo.

So I propose {} and %( ) are the best recommendations. Use the space, Luke.

[raiph]

While hash is a sure bet, I think we need to realize that it was always just poor doc that turned this into a problem. I urge folk to consider a return to respectful acceptance of the simple and natural nature of Larry's original DWIM and a recognition that it has successfully taken root.

Please note my latest StackOverflow attempt at formulating the precise {} hash vs block DWIM rule.

I'm going on a trip for a week, but if everyone is happy with it I will be happy to integrate it into the doc a couple weeks from now.

Imo the right way forward for the docs is to show respect for Larry's DWIM. This is consistent with jnthn's perspective and the majority of existing community usage and, I think, preferences, though I acknowledge some strong opinions against it. (I return to this aspect at the end of this comment.)

Perhaps the WAT side of this DWIM belongs on the traps page but I'm unsure. Please read the latest version of my Reddit discussion of this DWIM/WAT that complements my SO answer.

Imo the right way forward for the docs contributor style guide is to recommend use of the DWIM in all cases except where documenting the %(...) alternative and the hash routines. The current guide text contains multiple factual errors and points in the wrong direction imo:

Prefer the %() form of declaring hashes

Imo this should be "Prefer the {} form of declaring hashes".

my %hash := { this => "is", a => "hash" }; # Correct, but BAD
my %hash := %( this => "is", a => "hash" ); # GOOD

Imo this is inappropriately "disrespectful" to Larry's DWIM. (I get that the "disrespect" isn't emotive but just trying to be clear.)

Using the second form is more idiomatic

Idiom is natural to a native speaker. I'd argue that's much more {} than %().

and avoids confusion with blocks.

As we know, it unfortunately introduces confusion with %() which won't go away for a few years.

See also my discussion of strange consistency with hash subscripts and ugliness in pair literals in my reddit comment linked above.

This does not apply to empty hashes, which should be declared using {}:

Switching guidance to be use of the DWIM will eliminate this exception.

I understand that samcv and alex and others got burned over this dwim. I think that was down to poor doc. Perhaps my poor original SO answer didn't help. (Hopefully it's not so bad now.) I understand that what I'm saying almost certainly won't resonate for them. Getting burned a few times before the right mental model clicks leaves a lasting impression, especially if the right mental model still hasn't clicked.

But I'm hopeful that Larry's view (which is that the DWIM made sense), and the majority newbie view (which is that the DWIM is fine if no one tells them about it but rather just exposes them to it), and the view of some old hands (jnthn finds the DWIM simple and natural, as do many others including me), and the evident widespread use of this DWIM, and the prospect that improved doc and community understanding will be in place, are persuasive that disrespecting Larry's DWIM isn't the way to go but rather embracing it, at least for now, until we perhaps revisit this in another few years once %() has completed a deprecation cycle.

[raiph]

I posted my prior comment before reading the latest comments about speed. Those look dramatic and perhaps trump everything else. Perhaps {...} can be sped up? How is speed for :key{:a,:b} vs :key(%(:a,:b))?

I still think it makes sense to generally use {} as a hash constructor in docs, when an explicit constructor is needed, because it reads very well. We can document %(...) as being way faster and avoiding the {} hash/block DWIM/WAT though having the %() WAT.

[JJ]

But really, what is WAT?
I kind of agree with using {} so I guess that's an actionable thing that can be done right now. Do you still want this issue to be assigned to you to complete it?