On 2019-12-10 16:07, Trey Harris wrote:
On Mon, Dec 9, 2019 at 9:53 PM ToddAndMargo via perl6-users
<perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote:
On 2019-12-09 09:44, Trey Harris wrote:
> Signatures are important to Raku.
Trey,
The signatures are very important to the developers.
They only confuse the programmer.
I explained in the context surrounding the sentence you clipped out why
this is not true. (Assuming you’re defining “developers” as “programmers
who work on Raku compiler and language internals” and “programmers” as
“developers who have a working knowledge of Raku and use it regularly,
but do not work on internals”. If you made this distinction explicit
somewhere, I haven’t seen it.)
As I wrote in that earlier email, Raku puts a great deal of what would
in other languages be considered /language syntax into/ routine
signatures, and Signatures in Raku can do things that no other language
is capable of. (Most individual features thereof, there are other
languages that include them. But I don’t think any other language has
put such a rich set of them together before, especially in the context
of multi dispatch.) This means they /are/ important to the “programmer”
in your construction.
And, in fact, I find it difficult to understand why you’d think most
routine signatures would be /more/ useful to “developers” vs.
“programmers” in your formulation: if one is modifying a routine in core
or in the compiler, one has the definition, including signature, right
there—signatures in the docs are not intended for them. If one is
/using/ a routine in internals/core, or needs to refer to other versions
of a multi, then that “developer” is acting as a “programmer” at that
moment—they are using, not modifying, the routine in question, and yes,
the doc signatures are useful to them, but no more so than for any other
Raku programmer.
Let me make an observation on one of your earlier “keeper” emails, the
one that has been memorialized in the archive
<https://www.nntp.perl.org/group/perl.perl6.users/2019/12/msg7418.html>.
In it, beginning with the line where you repeat the signature verbatim,
here’s a few lines of what you’ve written:
|multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos --> Bool)
"multi method" This means there are multiple ways to address this, as in
multi method contains(Str:D: Cool:D $needle --> Bool) multi method
contains(Str:D: Str:D $needle --> Bool) multi method contains(Str:D:
Cool:D $needle, Int(Cool:D) $pos --> Bool) multi method contains(Str:D:
Str:D $needle, Int:D $pos --> Bool) "Str" means it want to be fed data
as a string. Str.foo [...] "-->Bool" means it return True or False |
in total, you spend 44 lines describing the signature. My observation is
this:
/*Your English description of the method’s signature could be
programmatically generated from the Signature itself.*/ (At least,
adjusting slightly for standardizing the description.)
The only way in which this assertion /isn’t/ true is your use of words
like “haystack” to try to explain the purpose of the arguments and verbs
other than neutral ones like “passes”, “references”, and “returns” and
instead use ones that are specific to the purpose of |.contains|—plus
your mention of “Index starts at zero by way of string convention in
Perl 6”—which I don’t entirely understand. (But if desired, all those
qualities could be added as machine-readable annotations to |.contains|
and other routines’ self-documenting Pods.)
I think there are two interesting conclusions to be drawn from this:
1.
If you think these 44 lines are tremendously useful and would be
more useful than the signatures, then they could, in fact, be
programmatically generated and inserted into every single routine’s
documentation. Since this would add a great deal of bulk to the
docs, perhaps this could be done as hover text (perhaps even so that
each part of your description appeared as you hovered over the
relating Signature text), or something that is found under a
disclosure button.
There would, of course, be some routines for which this
autogenerated description would be insufficient. But those are the
ones where docs text is already given over to usage descriptions.
2.
With the prior point stipulated, the question is raised: if you know
enough of Signatures to write what you wrote, how do you not “know
signatures”? If it’s because you spent a great deal of
trial-and-error to figure out what you wrote below the signature,
where those of us who understand Signatures just see (for the most
part) an algebraic expansion into 44 lines of English and
formatting—then perhaps the exercise of doing exactly what’s
described in the prior point would be a useful new feature for the
docs framework.
But for those of us who can read a signature and interpret it as an
extremely brief form of those 44 lines, eliminating the signature
for those 44 lines would not be a welcome change to the docs—to the
contrary, it would be bothersome and unnecessary verbosity making it
harder to understand the gestalt of a routine—and, especially,
patterns visible in variants of multis, which in this formulation
would be pushed off-screen from one another, interspersed with walls
of text.
If you /have/ tried reading the Signature class docs
<https://docs.raku.org/type/Signature> after first reading the brief
summary of them in the Functions language doc
<https://docs.raku.org/language/functions> and found them entirely
inscrutable, even under careful reading, then you will always be writing
what Larry once called “babytalk” Raku—since features like multis and
protos will be beyond your grasp.
I can’t reread everything you’ve written on this list, IRC, and GitHub,
but if you /have/ said you have tried to study signatures and found them
incomprehensible, I haven’t seen this. I do see you frequently asserting
that you (and/or other unheard-from programmers that you insist are out
there and are invisible because, you suggested elsewhere today, they
have abandoned Raku in disgust) “shouldn’t” have to do so—that Raku’s
signatures are not a worthwhile topic of study.
But that’s because—as you showed above with your flippant response that
did not engage with the larger point of my earlier email—you deny that
signatures are as important to Raku as they /are./
Those of us who have been Perl trainers are very familiar with a
particular phenomenon in Perl 5 instruction: some perfectly capable
students, for some reason, never learn regular expressions. They
cargo-cult, cut-and-paste, use GUI and web regex-builder tools—but they
/never actually learn to write regexes from scratch./
This is an enormous obstacle to doing text-processing in Perl; regexes
are such an important facet of the language that ignoring them makes one
a less-fluent Perl coder. But even after a trainer notices this issue
with their coding and tells them this—suggesting books and tutorials and
videos and even online games to teach them—some students just don’t ever
learn regexes.
And depending on the type of work they do, they may get by. Regexes
/can/ be a very isolable sublanguage of Perl if you want to ignore them
completely. But if they do so claiming to themselves and others that
“regexes are too difficult and they aren’t really all that useful”—which
is something trainers hear—that’s just not true.
Signatures are as important to Raku as regexes are to Perl. But
signatures in Raku—unlike regexes in Perl—are /not/ isolable.
At best, the designers of the routines you use were so good at their
designs that you can write working code just based on how you’d imagine
a routine should work and reading the signatures just for what might be
analogized to their “inactive ingredients” or “flavor text”—the names of
arguments and their ordering. (Plus plenty of trial-and-error, of
course.) If you write code only for yourself, this may be enough.
But you /will not/ write modules that others will find pleasant to use
or routines coworkers will find easy to modify without your
understanding signatures. And you /will be/ denying yourself a big chunk
of the language’s expressiveness, too—one of the features that makes it
unique among modern languages, and which I and others find a joy to use,
and one of the most excellent features of the language.
(Given your glib reply to my earlier, it may have been foolish of me to
have taken the time, not just reading your follow-ups today, but to go
back looking at prior threads you’ve been involved in. Perhaps you’ll be
just as dismissive of this message. But I choose to try one more attempt
at this, in hopes that you’ll give it due consideration.)
Hi Trey,
I do apologize if I came off as glib to you.
I am aware of
https://docs.raku.org/type/Signature
I currently have it open. It is really confusing.
It would help it is had an introduction explaining
the concepts involved, something like the 44 lines
in my keeper. I do not see any definition of what
the various syntaxes used stand for such as were
covered in my 44 lines. This need to come first,
not through osmosis.
Start small and work up. Take it as building block.
First we teach your what the concepts are what the
syntax means. Then show you how to use them
to read simple signature, then work up to the
big nasty ones. It is currently written as a
refresher to someone who already knows what he
is doing.
I think the signatures are a tool that the developers
use on a frequent basis. And judging by the results
(Raku), it is working fantastically for them. This
does not mean that they can not be of use to the rest
of us too. I don't find them very useful at the moment.
Those 44 lines you referred to are necessary at least
somewhere so as to make the signatures understandable.
Repeating them for every function would cause a lot
of bloat.
What I purpose doing is to use the technique that math
teachers use: explain the mechanics first and the
theory second. Instead of jumping straight the
signature, explain what the functions intended propose,
how to use it, then show the signature. "Ah ha,
so that is what that means."
This technique is very successful when used my math teachers.
I remember in college calculus, one teacher did it this way.
His course was a blast and I aced it. Another only taught
the theory. I barely made it through the class.
If you know the mechanics, it is much easier to pick up
the theory.
Don't expect anyone to understand a Fast Fourier Transform
as a requirement to learn simple math. Teach the simple math
first and build up.
And please, no one jump to the conclusion that I am
not appreciative of the work that was put in on the
docs. Technical writing in a arduous task and
requires a lot of skill and no one every thanks
them for it.
-T
p.s. part of the issue I have with the signature is that
they are often wrong and I don't have either the time
of the skill to reverse engineer them, so I don't
trust them. And reporting them results in a lot of
arguing.
The signature the developers use, who have their own specifications, are
obviously right or Raku would
be a gigantic mess.
