Named Arguments in Caller

[Larry Rix]

I frequently look at Client code calls to a supplier and have to spend extra time deciphering what the arguments are by name. Sometimes, it is enough to know the name of an argument to tell the story of what the argument is and its story. One such aspect of an arguments story might be, "What are my range of possibilities?"

As I am looking at the Swift language (not a fan, but), I am seeing an adopted grammar construct that is quite helpful. I will call them Named Arguments in the Caller.

Here's an example:

This one little line tells a great story, but the most interesting aspect is that I know for sure that the first argument is the "width" and the second is the "height". It is totally unambiguous, which is highly helpful in reading this code. I do not have to go find the "Resolution" object (in this case) creation and understand what the magic numbers "640" and "480" are about.

Still—you might complain that between the VGA and Resolution it's really obvious what 640 and 480 are all about. However, all we have to do is change context and that capacity to understand breaks down.

let Cat = Animal(2, 2, 4)

If you're like me, you are struggling with what 2, 2, and 4 are about in the context of Animal. Now, read it again:

let Cat = Animal(ears: 2, eyes: 2, legs: 4)

Suddenly, without having to go look at Animal, I sufficiently understand 2, 2, 4, whereas before, I was lost.

All I am asking for is that Eiffel is given this enhancement as an option, where arguments in a caller can be "tagged" similar to how we tag contract assertions.

[Woland's Cat]

I would also like this. You can already do it in TUPLEs, which is occasionally useful.

- t

[Eric Bezault]

What about if EiffelStudio displays this information when you mouse
over the caller?

--
Eric Bezault
mailto:er...@gobosoft.com
http://www.gobosoft.com

On 09/09/2020 20:23, Larry Rix wrote:
> I frequently look at Client code calls to a supplier and have to spend
> extra time deciphering what the arguments are by name. Sometimes, it is
> enough to know the name of an argument to tell the story of what the
> argument is and its story. One such aspect of an arguments story might
> be, "What are my range of possibilities?"
>
> As I am looking at the Swift language (not a fan, but), I am seeing an
> adopted grammar construct that is quite helpful. I will call them Named
> Arguments in the Caller.
>
> Here's an example:
>

[Woland's Cat]

On 09/09/2020 19:37, Eric Bezault wrote:

What about if EiffelStudio displays this information when you mouse
over the caller?

The IntelliJ solution. It's very useful.

--
Thomas Beale
Health IT blog | Culture blog | The Objective Stance

[Gachoud Philippe]

THAT WOULD BE SO GREAT!!! I find that Estudio lacks of hover informations just something like all instances of selected word into class for ex too. Sry out of topic... What about if EiffelStudio displays this information when you mouse
over the caller?

--
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/eiffel-users/786b699c-5b39-dab8-e707-c5023ca1e0dd%40gobosoft.com.

--

**********************************************

Philippe Gachoud

Puerto Williams 6657

Las Condes

Santiago de Chile

+56 934022210
ph.ga...@gmail.com

RUT: 26374747-k

**********************************************

[Larry Rix]

Hi Eric,

That's okay, but it's work. I just want to read it. Also, it may be that my Clients context is slightly askew of the Supplier, so having argument tags on the Client caller allows me to define what those arguments are in terms of the Client and not the Supplier. That said—perhaps auto-complete can initially provide me with the argument tag names based on the argument identifiers in the supplier, but then I can change them as needed.

This might be especially true for inanely named arguments like "s: STRING" and "v: INTEGER" where even the supplier-based argument names are horrible story-tellers for me to understand the story of what my Client is trying to achieve.

In the case of "s" and "v", even a mouse-hover is just about worthless, unless the feature name gives me the context well enough.

I just want that choice so I can make my code more readable—even to myself months and years later.

Cheers!

Larry

[Larry Rix]

For example: ARRAYED_LIST.extend (v: [like item] G)

The 'v' is great for the ARRAYED_LIST class, but it is designed to be generic. It doesn't know where and in what context it will be applied.

However, in the client, we suddenly have context—much richer in terms of its story than just 'v'. So, when my client calls 'extend', I want that argument passed to carry its context.

This code example (mock-up below) might not be the best off-the-cuff, but it expresses something about what I am pointing at:

feature {NONE} -- Initialization

make

-- Run application.

local

l_animal: attached like animal_anchor

do

create animals.make (100)

create l_animal

animals.extend (dog: l_animal)

create l_animal

animals.extend (cat: l_animal)

create l_animal

animals.extend (mule: l_animal)

end

animals: ARRAYED_LIST [ANY]

animal_anchor: detachable like ANY

end

The idea is hopefully clear: From a strictly "story-telling" view, my code now tells a really good story. It's not just about knowing that the argument for 'extend' is 'v' and that "generic" story of ARRAYED_LIST. What I am really wanting to do is tell the story of my use of 'v' within the context of my client code. Now, it may well be that 'v' is good enough or even that 'extend' is good enough for my client story. In many cases, it is. But there are those cases where this expressiveness of story-telling-code (Self Documentation Principle) helps my reader truly "get" what I am trying to do!

NOTE: Swift is trying to just repeat the argument names in the client because it needs this convention to disambiguate one creation init procedure from another creation init procedure. That is not what I am after. I am after what Eiffel has already firmly established for me in other areas—that is—story-telling self-documenting tags. I find it further intriguing that this "tag" would show up in error messages as well!

[Ulrich Windl]

>>> Larry Rix <lar...@moonshotsoftware.com> schrieb am 09.09.2020 um 20:23 in
Nachricht <5664214d-2860-423e...@googlegroups.com>:

> I frequently look at Client code calls to a supplier and have to spend
> extra time deciphering what the arguments are by name. Sometimes, it is
> enough to know the name of an argument to tell the story of what the
> argument is and its story. One such aspect of an arguments story might be,
> "What are my range of possibilities?"
>
> As I am looking at the Swift language (not a fan, but), I am seeing an
> adopted grammar construct that is quite helpful. I will call them Named
> Arguments in the Caller.
>
> Here's an example:
>
> [image: swift_named_arguments.JPG]
> This one little line tells a great story, but the most interesting aspect
> is that I know for sure that the first argument is the "width" and the
> second is the "height". It is totally unambiguous, which is highly helpful
> in reading this code. I do not have to go find the "Resolution" object (in
> this case) creation and understand what the magic numbers "640" and "480"
> are about.

Hi!

I think such a feature is useful for languages where there are optional
parameters and where you can change the order of parameters.
In Eiffel well-designed routines should not have many parameters anyway, so
that shouldn't be a big issue.
Also the extra typing required may be a problem for some people.
Furthermose I would not like the variants being mixed all the time
Resolution(witdh: 640, height 480)
Resolution(height 480, witdh: 640)
-- with 3 parameters you would have 6 variants already and with 4 it'll be 24

>
> Still—you might complain that between the VGA and Resolution it's really
> obvious what 640 and 480 are all about. However, all we have to do is
> change context and that capacity to understand breaks down.
>
> let Cat = Animal(2, 2, 4)
>
> If you're like me, you are struggling with what 2, 2, and 4 are about in
> the context of Animal. Now, read it again:
>
> let Cat = Animal(ears: 2, eyes: 2, legs: 4)

That type of object would be rather untypical, because an Animal(3,1,2) would
be a different type of animal. What would those have in common? Cat probably is
a Class derived from Animal, so you simply create a Cat.

>
> Suddenly, without having to go look at Animal, I sufficiently understand 2,

> 2, 4, whereas before, I was lost.
>
> All I am asking for is that Eiffel is given this enhancement as an option,
> where arguments in a caller can be "tagged" similar to how we tag contract
> assertions.

Please no "comittee bloat" (add everything that might be useful is some cases
for someone in the future).
Old saying: "It's perfect when you can't remove any more, not if you can't add
any more"

Regards,
Ulrich

[Ulrich Windl]

>>> Larry Rix <lar...@moonshotsoftware.com> schrieb am 09.09.2020 um 21:19 in
Nachricht <b2f61982-0184-421f...@googlegroups.com>:

> Hi Eric,
>
> That's okay, but it's work. I just want to read it. Also, it may be that my

> Clients context is slightly askew of the Supplier, so having argument tags
> on the Client caller allows me to define what those arguments are in terms
> of the Client and not the Supplier. That said—perhaps auto-complete can
> initially provide me with the argument tag names based on the argument
> identifiers in the supplier, but then I can change them as needed.
>
> This might be especially true for inanely named arguments like "s: STRING"
> and "v: INTEGER" where even the supplier-based argument names are horrible
> story-tellers for me to understand the story of what my Client is trying to

> achieve.
>
> In the case of "s" and "v", even a mouse-hover is just about worthless,
> unless the feature name gives me the context well enough.

I disagree: In Eiffel, you'll have to explain the formal parameters in a
comment, and the name of it is mostly useful inside the routine. Agreed, good
names may help you to remember what a parameter is, but for routines with just
one parameter "s:STRING" may be perfectly acceptable.

>
> I just want that choice so I can make my code more readable—even to myself
> months and years later.
>
>
> Cheers!
>
> Larry
>
> On Wednesday, September 9, 2020 at 2:38:02 PM UTC-4 er...@gobosoft.com
> wrote:
>
>> What about if EiffelStudio displays this information when you mouse
>> over the caller?
>>
>> --
>> Eric Bezault
>> mailto:er...@gobosoft.com
>> http://www.gobosoft.com
>>
>

> --
> You received this message because you are subscribed to the Google Groups
> "Eiffel Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to eiffel-users...@googlegroups.com.
> To view this discussion on the web visit
>

https://groups.google.com/d/msgid/eiffel-users/b2f61982-0184-421f-b189-1bb350

> e05503n%40googlegroups.com.

[Ulrich Windl]

>>> Larry Rix <lar...@moonshotsoftware.com> schrieb am 10.09.2020 um 01:25 in
Nachricht <d3bf3987-acfa-4b21...@googlegroups.com>:

Actually I fail to see what your example is illustrating. Also you obviously
left out the comment describing feature "extend" at the beginning.

>
> --
> You received this message because you are subscribed to the Google Groups
> "Eiffel Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to eiffel-users...@googlegroups.com.
> To view this discussion on the web visit
>

https://groups.google.com/d/msgid/eiffel-users/d3bf3987-acfa-4b21-85f9-959dda

> c09203n%40googlegroups.com.

[Larry Rix]

Perhaps I am not being clear. Comments are for the Supplier code and mouse-hovering. I don't want to have to mouse-hover or pull up the Supplier source to read the comment.

When I type the call to the Supplier from the Client caller, I want to have a tag in front of what I am sending as an argument that describes that argument from the viewpoint of the caller in its context regardless of what the Supplier has to say about it.

I get what you're saying about Supplier comments and argument names. I am not talking about those. I am not talking about mouse-hovers and so on. Honestly, I don't particularly care what the Supplier argument name is in this case. In other cases, I do. In this case, I don't have any choices because I cannot do tags on Client caller arguments being sent. This is especially annoying when I have to send "magic numbers" that have no context in and of themselves.

[Eric Bezault]

On 11/09/2020 4:39, Larry Rix wrote:
> This is especially annoying when I have to send "magic numbers" that
> have no context in and of themselves.

At work our style guidelines say that we should not use
magic numbers. We should use constant attributes instead.
That way these numbers are not magic anymore. They have
names and comments. And if they are used in multiple
places and their value changes, we just have one place
to update.

As for this example:

make
-- Run application.
local
l_animal: attached like animal_anchor
do
create animals.make (100)
create l_animal
animals.extend (dog: l_animal)
create l_animal
animals.extend (cat: l_animal)
create l_animal
animals.extend (mule: l_animal)
end

I would rather write:

make
-- Run application.
local

l_dog: attached like animal_anchor
l_cat: attached like animal_anchor
l_mule: attached like animal_anchor
do
create animals.make (100)
create l_dog
animals.extend (l_dog)
create l_cat
animals.extend (l_cat)
create l_mule
animals.extend (l_mule)
end

[Ulrich Windl]

>>> Larry Rix <lar...@moonshotsoftware.com> schrieb am 11.09.2020 um 04:39 in
Nachricht <4ae80ab2-4f3b-4fa5...@googlegroups.com>:

> Perhaps I am not being clear. Comments are for the Supplier code and
> mouse-hovering. I don't want to have to mouse-hover or pull up the Supplier
> source to read the comment.

Hi!

You may not want it, but the comment is part of the "contract" actually.

...

[Larry Rix]

> Also the extra typing required may be a problem for some people.

I love Bertrand's quote on this: "There is no tax on keystrokes."

 

[Larry Rix]

Furthermose I would not like the variants being mixed all the time
Resolution(witdh: 640, height 480)
Resolution(height 480, witdh: 640)
-- with 3 parameters you would have 6 variants already and with 4 it'll be 24 

I never suggested that one has the capacity to change the order of the arguments in the caller, only to add tags in from of the argument objects.

 

[Larry Rix]

At work our style guidelines say that we should not use
magic numbers. We should use constant attributes instead.
That way these numbers are not magic anymore. They have
names and comments. And if they are used in multiple
places and their value changes, we just have one place
to update. 

I use the precise same style guidelines for the exact same reasons. One can make a strong argument for it, which is precisely why I follow the guideline closely. However, I find myself in a temporary violation of that guideline when the code is coming together for the first time.

I will write the magic numbers because it is the easiest thing to do at the start. Later, I will put on my "replace-magics-with-constants" hat and revisit the new code, replacing magic numbers with constants en-masse. I find that this is a multi-step phase. It is not enough to wave one's hand and say, "Yeah, create a constant and reference it here." There is more to it than that.

If I am on-my-game, I have a design pattern for constants, whether they are stored in the same class, referenced from somewhere else, or inherited. Deciding how to do that is a step for the "magic-number-replacement" hat cycle and not for the spur-of-the-moment first-coding cycle.

What the in-situ caller argument-tagging offers me is the capacity to name my constants in-place temporarily (or longer-term if I choose), and pushes off the work (labor) of thinking through the "how-do-I-want-to-place-these-constants" until sometime later. Having a constant-handling-design-session in the midst of another design session complicates things and complex things slow me down and perhaps are the source of bugs and even more labor later on.

All I am really asking for is a choice instead of being forced into a box right out of the chute. 

 

[Larry Rix]

I would rather write:

make
-- Run application.
local

l_dog: attached like animal_anchor
l_cat: attached like animal_anchor
l_mule: attached like animal_anchor
do
create animals.make (100)
create l_dog
animals.extend (l_dog)
create l_cat
animals.extend (l_cat)
create l_mule
animals.extend (l_mule)
end

Sigh—I knew this was coming. Yes—I would write the same thing for the most part. That's a given. I got it.

I might even go so far as to declare the locals as: l_dog, l_cat, l_mule: attached like animal_anchor.

But these are nuances of style and neither of us is wrong. Style is style, where some styles work out better than others. That's a settled matter that I think we might agree on.

Again—the issue is choice. Not all code is written nice and tight at the start. There are a number of styles and choices in design and code layout and so on. That is a part of what we do.

I am pointing at the nether-world between initially writing and where I circle back and really think through my design and what's best for the long haul. In the interim time, I want to leave breadcrumbs behind me. Perhaps I will clean those up today, perhaps tomorrow, and perhaps months from today. Perhaps I will find a niche where the breadcrumb becomes the best choice and leave it as-is forever.

And what of the instance where I start writing the code and have to turn that code over to another programmer who has not been in my head with intimate knowledge of what I was writing, why, and what names I had in mind for those constants? Having those breadcrumbs is a great way for me to communicate what was in my mind and the direction I was going.

Sure—I can write a comment. Like I wrote to Ulrich, there is no tax on keystrokes and I can add comments on that caller.

BUT—what if I want to search my code using Eiffel Studio and have it tell me, "Where are all my argument tags that I need to look at?" Comments won't take me there (unless I adopt a comment-structure-convention style -- uggggh). It would be so much more handy and simple to have my compiler not complain about argument tags in the caller.

Finally—what if my Supplier argument has a range of possibilities, where my caller sends in one of them. The point where my caller is making the call, I would like to add a tag that tells the reader of my caller (perhaps myself months later) instantly what that range is from my callers perspective (it might be something less than the Supplier dictates).

I just want the choice to be there so I can discover.

Adding the capacity for an OPTIONAL tag would break nothing in existing code anywhere for anyone. It's a very safe addition to the grammar.

[Ulrich Windl]

>>> Larry Rix <lar...@moonshotsoftware.com> schrieb am 11.09.2020 um 14:58 in
Nachricht <11e2884b-00f4-4f90...@googlegroups.com>:

>>
>> > Also the extra typing required may be a problem for some people.
>>
>
> I love Bertrand's quote on this: "There is no tax on keystrokes."

But also programmers are not paid per key stroke.

[r...@amalasoft.com]

But, there is a penalty for poor signal-to-noise ratios

That is why it has been recommended to use arg and local names that are terse but clear.  The 'set_this' example having only 'v' as an argument is an excellent example.

Carrying that too far gets us into serious trouble of course.

A feature or parameter name must be as short as possible, but no shorter.

Feature names should be as "obvious" (clear to the _reader_) as possible while still not consuming excess visual (and intellectual) real estate.

It's a balance that should come from experience and, perhaps more importantly, from empathy with the reader of that code.

Code will have errors.  To find the errors, we must be able to understand the code.  To understand the code, we must be able to read the code.  It follows then that readability (not to be confused with verbosity) is the most important characteristic of code.  Writability ain't (despite the loud advocacy for cryptic, son-of-APL syntaxes).

Tools that improve the chances that we can comprehend code are always welcome (and often insufficient), but are no substitute for disciplined coding practices, whatever the language being used.

Tools also must not interfere with the code creation or consumption.  A "cool" feature to some might be a pain in the butt to others, especially if it is imposed on the process.  As such, any such feature, regardless of its thermal characteristics (cool or hot) must be optional unless and until is is proven to be essential (if ever).

My bank balance is now depleted by $0.02

Thanks

R

-------- Original Message --------
Subject: Re: [EXT] [eiffel-users] Named Arguments in Caller
From: Larry Rix <lar...@moonshotsoftware.com>
Date: Fri, September 11, 2020 8:58 am
To: Eiffel Users <eiffel...@googlegroups.com>

> Also the extra typing required may be a problem for some people.

I love Bertrand's quote on this: "There is no tax on keystrokes."

 

--
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/eiffel-users/11e2884b-00f4-4f90-9c23-68079b4e2fc5n%40googlegroups.com.

[Bertrand Meyer]

Information through mouse hovering in EiffelStudio: yes, very good suggestion.

 

As to the language extension: I am not convinced of its necessity, but should it be implemented it’s clear it should be the following.

 

- Alternative to Actual_list, as a new possibility in Actuals: Tagged_actual_list. (In other words either all or no actual argument are tagged.)

- A tagged actual is of the form formal_name: expression where formal_name is the name of the corresponding formal in the declaration. (No sense in giving different names to the same thing, one the formal argument name and the other as tag – would only seed confusion).

- Conventions are the same for tuple expression as for argument lists in calls, i.e. one can write [author: “Tolstoy”, title: “War and Peace”].

 

-- BM

To view this discussion on the web visit https://groups.google.com/d/msgid/eiffel-users/20200911081215.cf48dd763fcaf5d42559c6c92f6fc53b.57f7e51eee.wbe%40email25.godaddy.com.