Re: Ada Quality and Style book discussion

[Anonymous Coward <spam@spam.com>]

In article <m264qrhu52.fsf@grendel.local>, Simon Wright wrote:
> 
> There's an interesting point here. It makes a lot of sense to me to
> make subprogram parameter names as helpful as possible to the
> caller; this includes naming them 'from the outside' without any
> regard as to how clumsy things may seem from the inside.
> 
> One could always use renaming to name the parameters more
> conveniently from the inside view, though it would have to be a
> pretty extreme case to justify it I would have thought.
> 
> As an extreme case, we had a message sending procedure declared like
> 
>   procedure Send (Message_In : String; To_The_Stream : Stream);
> 
> because from the writer's point of view Message_In was indeed an
> input to his procedure. Of course from the reader's side it makes no
> sense at all.
> 
> Much better as
> 
>   procedure Send (The_Message : String; To_The_Stream : Stream);
> 
> or even (if the package name is suitably descriptive and there aren't
> many other Sends in scope)
> 
>   procedure Send (S : String; To : Stream);
> 
> called as
> 
>   Send ("hello world!", To => Output);

Even better yet would be to avoid taking a position such that the
usage is only correct or readible from one perspective and not
another.  The excessive use of articles is at the core of problem in
your first example.  Here's how I might code it:

   procedure Send (Message : in String; Target : in Stream);

It's not clutsy from the inside or the outside, it's concise (with no
distracting articles), and it doesn't mislead.  It assumes the
audience/reader knows Ada.  If the reader doesn't know basic Ada, then
the problem is with the reader, not the code.