On Sat, Feb 16, 2013 at 9:14 AM, Staffan Tylen <staffan.ty...@gmail.com>wrote:
> Quite some time ago I made some comments on the use of place-holding
> commas in parameter lists and the way they are documented. I didn't receive
> any reaction on this at the time (maybe something went wrong with my
> posting)
>
Hi Staffan,
I did reply to the first posting you did. I said that all arguments are
positional and that if you omit an argument you have to use a comma to keep
the arguments in their correct position. I think this is fundamental to
Rexx in general, at least it is fundamental to ooRexx.
I went back and looked at your posting and I see that I didn't reply to
your follow up, I vaguely thought I had. I was *sure* that I had put
some clarifying text in the How to Read the Syntax Diagrams section. But,
I see that I have not done so. ;-(
> and I forgot about it until now when I looked at the following description
> of the createStaticText method:
>
>
> >>--createStaticText(-+------+--x-,--y-+------+-+------+-+----------+-+--------+-)-><
> +-id-,-+ +-,-cx-+ +-,-cy-+ +-,-style--+
> +-,-text-+
>
>
In the above, it is sort of a unique situation with the leading id argument
being optional. I would never have introduced that in a new method. In my
opinion the id argument should be required, but because of backwards it has
to be optional. So, I'm not real happy with how that one looks.
This in my opinion is a good example that illustrates the confusion that
> can be created when reading it. The lower line identifies the optional
> parameters but what I react on here is that the commas are listed there as
> well. If I strictly follow this to create a static text object without a
> resource ID, I would write it like this:
>
> createStaticText(posX, posY, posCX, posCY, myStyle, myText)
>
>
But, your thinking is wrong. ;-) If you stop and repeat to yourself 100
times: In ooRexx all arguments are positional; if I wish to omit an
argument I MUST use a comma. Then I don't think you will have trouble with
this any more.
> But without testing it I think that the correct coding should be:
>
See, you already understand this.
>
> createStaticText(, posX, posY, posCX, posCY, myStyle, myText)
>
> In the same way the following method call should be correct as well
> according to the doc, but of course it isn't:
>
> createStaticText(posX, posY, myText)
>
> Based on this I am of the opinion that the parameter list is better
> documented like this:
>
>
> >>--createStaticText(-+----+-,-x-,-y-,-+----+-,-+----+-,-+-------+-,-+------+-)-><
> +-id-+ +-cx-+ +-cy-+ +-style-+
> +-text-+
>
> Here there are no optional commas, which is the norm when writing a
> parameter list. There are exceptions to this, like the ListView 'add'
> method, which allows for a variable number of commas, but such exceptions
> are few and the variable comma seems to be documented "correctly".
>
> What's the general view on this?
>
I am of course interested in hearing every one's view on this.
My view is:
Your opinion that the parameter list is better documented the way you show
is a good opinion. I am not going to argue that the current style is more
correct than your preference. If you had brought this up 4 years ago when
I first started rewriting the doc to remove its inaccuracies I would have
likely adopted that style instead of the style I did adopt.
However, I think the current style is understandable. I did intend to put
a clarifying statement in the section on how to read the syntax diagrams
for this point. I'll be sure and do that.
It already has a statement that in all cases, the text rather than the
syntax diagram should be considered definitive. If you couple that
statement with knowledge that in ooRexx if you omit an argument you must
use the place holder comma, I don't think there is any ambiguity.
I'm not going to go back and change all the already done syntax diagrams.
If some one wishes to prepare a patch that changes *all* the syntax
diagrams at one time to the style you propose, I'll gladly apply the patch
and use that style from then on.
--
Mark Miesfeld
------------------------------------------------------------------------------
The Go Parallel Website, sponsored by Intel - in partnership with Geeknet,
is your hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials, tech docs,
whitepapers, evaluation guides, and opinion stories. Check out the most
recent posts - join the conversation now. http://goparallel.sourceforge.net/
_______________________________________________
Oorexx-users mailing list
Oorexx-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-users
