Re: Ada Quality and Style book discussion

[Simon Wright <simon@pushface.org>]

Anonymous Coward <spam@spam.com> writes:

> The project I worked on that banned "_Type" also tried to encourage
> developers to choose identifiers that make a complete grammatically
> correct english sentence, as if it were more important that
> non-technical folks could read the code than the maintainers.  
>
> It didn't work out too well, because when you make an english sentence
> in one usage, the same identifers make the code look like crap where
> an english sentence doesn't exist.  ie.
>
>    function compute_altitude (using : in temperature;
>                               and   : in dew_point;
>                               with  : in pressure) return altitude is
>    begin
>
>       return (using + and / with);
>
>    end compute_altitude;
>
> Obviously that's a bogus formula.. but it should be clear from this
> that making code read like english down to the point of including
> articles like "and", "with", "is", asks for disaster.  Some folks
> really complied with this direction, and wrote code like that function
> above - I'm not joking.

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);