Subject: RE: OCP Core version head_sid6 available

From: "Martin Stecher" <[email-masked]>
Date: Fri, 23 May 2003 14:31:45 +0200

> 
> > How about just calling the command with its full name and then only
> > refering to the abbreviation as the code in the technical
> > description.
> > Example
> >
> >     7.1 The connection-start command
> >
> >         command code: CS
> >         anonymous parameters: none
> >         ...
> 
> Would you use "CS" or "connection-start" in the examples? Full names
> make examples much more readable and make readers feel like they
> immediately know what is going on...

Due to the unnamed parameters, readers will need to refer to the command descriptions all the time anyway to be able to understand the examples.
So, I would stick with "CS" in the examples and better add more comments to the examples that help faster understanding of what is going on.

> 
> Looking from the other point of view, what are the technical reasons
> for NOT allowing full names on the wire? We can probably convince most
> developers to use abbreviations while supporting full versions. The
> amount of extra code or memory needed to support both versions is
> minimal. Are we concerned with extra bandwidth and CPU cycles spent on
> handling full versions if some broken implementation sends them?

Certainly it is not a big deal to program in a way that short and long names are supported but if you know that command names will never exceed three or four characters, there may be a chance for some optimizations.

> 
> Or are we primarily concerned that some implementations will end up
> recognizing one version (full or abbreviated) and not the other?
> 

While most implementations would use the abbreviated version, it is likely that full-name support is less well tested and has some limitations or hidden bugs that are not found during normal testing procedures.

Regards
Martin

---

From: Alex Rousskov <[email-masked]>
Date: Fri, 23 May 2003 09:12:11 -0600 (MDT)

On Fri, 23 May 2003, Martin Stecher wrote:

> > Would you use "CS" or "connection-start" in the examples? Full
> > names make examples much more readable and make readers feel like
> > they immediately know what is going on...
>
> Due to the unnamed parameters, readers will need to refer to the
> command descriptions all the time anyway to be able to understand
> the examples. So, I would stick with "CS" in the examples and better
> add more comments to the examples that help faster understanding of
> what is going on.

OK. If there are no further suggestions, let's try this approach.

Alex.