DefMod Syntax

[Tony van der Hoff]

On Wed, 15 Mar 2000, at 18:15:56, Jonathan Coxhead
<jonathan at doves.demon.co.uk> wrote on the subject "DefMod Syntax":

>   There were 2 votes to leave it out altogether, I think. I don't 
>see that the need to vary the system for Wimp_WindowInfo and 
>WimpSlotSize is big argument against. Wimp_WindowInfoChanged (if 
>that's what it means---I have no idea!) and Wimp_NewSlotSize aren't 
>bad names, e g.
>
>   I wouldn't have mentioned it, except you brought it up. 

Well, you did raise the issue initially ;-)

>Whoever 
>does the work, makes the decision. That's my view.
>

OK, having solicited your advice, I hope you won't mind if I don't take
it. I think it's just a matter of personal preferences, but so as not to
appear totally arrogant, I'll try to explain my reasoning:

I see the structure name as consisting of the module identification
(e.g. Wimp_), a generic structure type (e.g. Message), and a specific
message name (e.g. WindowInfo). All these parts carry useful information
to the programmer; the Structure Type name contains a very clear
indication that we are referring to a Message structure, transmitted by
Wimp_SendMessage, and received by one of the 3 User_Message Wimp events;
and the detailed message name is the same as that used by the PRM.

I think we all agree, therefore, that the nomenclature you adopted
initially was ideal; it agrees with the usage in the PRM, and I think
the classification is useful and intuitive.

We also agree that to maintain backwards compatibility, this identical
nomenclature is not available to us, and we need to find alternative
names. As I see it we have the option of changing the Message prefix, or
the detailed message name suffix, or both. 

This is perhaps where our preferences diverge. I believe that the
Message prefix should be retained in some form for the sake of clarity.
For this reason I'm not too happy about dropping it completely; it
detracts from the descriptiveness of the names, which I believe is a
major factor which you originally designed in to OSLib, often at the
(justified) expense of verbosity. There is another consideration: If and
when the basic message structure gets extended to more than 256
characters, then we will need to invent yet another new name. Having it
based on "Message" allows it to be called ExtendedMessage, or something.

Secondly, I would prefer the detailed message name to remain the same as
currently used by OSLib; this matches PRM usage (the fact that not all
of the messages we are considering appear in the existing PRMs is an
added complication), but equally important, it keeps things consistent
across versions of OSLib. Changing it would again detract from the
previous clarity existing in OSLib names, and needlessly cause confusion
to users. I really think this should be avoided.

This leaves us with the prefix. I'd prefer it to retain the generic
name, although I would consider abbreviating it if it could retain the
same meaning. Thus "Msg" is a possibility, "Mess" is naff, "M" is used
elsewhere, and I don't think there are too many other options.
Alternatively I could pre-or postfix it. NewMessage, NMessage,
WimpMessage, HeadedMessage were all considerations. My favorite remains
FullMessage; it is hardly a major increase in length, and even with the
suffixed part, message name lengths won't contend for records within
OSLib.

I cannot see any advantages (apart from limiting verbosity) conferred by
your suggested scheme of dropping the "Message" prefix, and then to
overcome the problems that creates by inventing new message names, thus
further compromising the existing scheme. Oh, yes, the two examples I
quoted from the Wimp module were not, of course, the only ones;
practically every module had one or more clashes; and following your
suggestion through would result in more and more imaginative structure
names. I really liked what you called them previously.
>
>   I think it's either an inconsistency between what should be the 
>same names in 2 different structures (Wimp_Message, Wimp_Message- 
>Header), or else it breaks compatibility. 

I don't understand what you are saying here. There is only one structure
in each case.

>It also seems odd to change 
>the name in the header, when that is the logically prior structure. 
>Why not "xfer_size", "sender_name", etc? (But only in the 
>Wimp_RamXfer, Alarm_Set structures, of course, whatever you call 
>them. Wimp_MessageRAMXfer, Alarm_MessageSet have to stay as-is.) So 
>we get the inconsistency of names, which is a shame, but resolved it 
>in the opposite direction.
>
>   The logic is this: the Wimp_MessageHeader names are used all the 
>time by everyone who uses Wimp messages, so should remain consistent 
>with existing practice. The names in the RAMXfer structure are only 
>used by people using RAM transfer messages, and there must logically 
>be fewer (<=) of them. So they get to pay the higher price of 
>learning a few new names. Ditto for Alarm_Set, etc etc.
>
Well, yes, we'd all prefer it that way if we were starting from scratch,
and you may well argue that we *are* doing so in this case. However, I
see it as superimposing a new structure (the header) over the existing
structures. For the sake of backward compatibility the names in the
header have to comply with existing structures. I know this is not
necessary from a code point of view, but a 'conceptual' backward
compatibility should also be maintained. I believe that retaining
consistency across the old and new structures is far more important than
idealising the logical structure. Maybe I'm taking the ideal of
backwards compatibility just one step further than you... 

> | On the subject of name clashes, Tom, you will need to do something
> | similar for your gadget object structure: "flags" is duplicated in
> | many objects - I've called it "gadgetflags".
>
>   Again, I think the opposite resolution should be used. The base 
>structure is fully entitled to use short names: it's up to the 
>clients who extend the base structure by inheritance to avoid the 
>names in the base.They can always do this.
>
And again I disagree ;-) However, this is Tom's end of the ship, and if
he wants to send me a set of patches for each of the gadgets, I'll be
happy to apply them.

On Fri, 17 Mar 2000, at 18:47:50, Tom Hughes <tom at compton.nu> wrote on
the subject "DefMod Syntax":
>
>Plus the base structure is already in use with the current names
>so we can't change them very easily.
>
I read that as agreeing with my philosophy?

Meanwhile, I'll defer making a further release until Tom has either
agreed to my fix, or has had time to send me the patches.

>   But, whatever you want :-)

Thanks for that; in the end, I guess it's just a matter of personal
taste :-)

Cheers,

-- 
Tony van der Hoff         |  Mailto:tony at mk-net.demon.co.uk
                          |  Mailto:avanderhoff at iee.org
Buckinghamshire, England  |  http:www.mk-net.demon.co.uk