Re: Question about record rep spec placement

[rgilbert@polaris.orl.mmc.com (Bob Gilbert)]

Ken Garlington <GarlingtonKE@lmtas.lmco.com> writes:
> 
> Maybe a simple example would help:
> ---
> package Device_IO is
> 
>   type Priority_Type is ( Normal, Urgent );
>   type Port_Type is range 0 .. 2#111#;
>   type Data_Type is range 0 .. 16#FFF#;
>   
>   type Message_Type is record
>     Priority : Priority_Type := Normal;
>     Port     : Port_Type;
>     Data     : Data_Type;
>   end record;
>   
> private
> 
>   for Message_Type use record
>     Priority at 0 range 0 .. 0;
>     Port     at 0 range 1 .. 3;
>     Data     at 0 range 4 .. 15;
>   end record;
>   
>   for Message_Type'Size use 16;
> 
> end Device_IO;
> ---
> 
> The way we intend a clients to read this is: You can
> assume that a Message has components Priority, Port, and
> Data, with the types shown. However, there are no guarantees
> as to the size of a Message, the placement of components
> within that message, the number of bits each component will
> use, etc. being stable from release to release. (In some
> cases, of course, you can use attributes to determine the
> current values, but it's up to the client to protect himself
> from changes in those attribute values.)

This may be your intent, but if I were a client and unless I was
very familar with this coding practice, I would only be confused
(admittedly not a difficult task) by this.  I would probably assume
that the author had at one time defined Message_Type as a private
type, and for some reason later decided to make Message_Type
non-private by moving the declaration out of the private section
and simply forgot to bring along the rep clause.

> What happens if I leave off the word private? In that case,
> I will be giving tacit permission for the user to do
> things like use Unchecked_Conversion to convert between
> Messages and 16-bit integers (as an example). You could argue that
> this is poor programming practice, but as least as far as
> how I understand the idea of programming by contract, if
> you put it in the visible part of the package spec, the assumption is
> that the client can take advantage of this information.

I realize that you are attempting to offer a hint to the client
that you really don't think he should be making use of the data
representation to do things like Unchecked_Conversion, but I am
afraid that the hint might easily be mis-interpreted or simply
missed, while you have done nothing to prevent any possible misuse
of the data. I would think some comments explaining why the rep 
clause is in the private section would be in order, but if you do
that you might as well have the comment explicitly state that you
don't want the client to make use of the rep clause, and leave the
rep clause with the type declaration.

> I could certainly declare a Message as a private type, and
> provide operations to manipulate its contents. However,
> there are cases where I'm not really adding much to the
> strength of the interface by adding the extra code.

I agree (sort of), but if it is so important to go to the trouble
of offering hints to the client that the data representation is 
proprietary, then I think it is important enough to just go ahead
and make the type private.  While doing this still doesn't protect
from Unchecked_Conversion, it does make a much stronger statement
that you don't want the client messing with the data or performing
any processing that requires knowledge of the data's representation.

What I do agree with is that many times the representation clauses
are of little or no value to the client and simply add clutter to 
a package spec making it more difficult to read.  This is where I 
think it would be nice if there was a way to provide the rep clauses 
(or for that matter, the entire private section, after all if the
client isn't supposed to have knowledge of the types details why
put them all there in the private section to see?) somewhere else, 
perhaps even defering them to a place in the package body (although 
I understand that I am simply looking at this from a human readability
side and there may well be serious compiler issues with this).

-Bob