On Mon, Dec 9, 2019 at 9:53 PM ToddAndMargo via perl6-users < perl6-users@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.)
