Re: Warning: Religious naming convention discussion :-) [was: assign help!!]

["John G. Volan" <johnvolan@sprintmail.com>]

Robert Dewar wrote:
> 
> In my programming the name clash that I most often come across is something
> like
> 
>     Parent : constant xxx := Parent (K);

Just out of curiosity, what is "K"?  "Key"?  "Kid"?  "Kludge"?  :-)

> now of course I don't want to use the same name in both places here, and
> I have not really settled on a convention. I don't like The_Parent, because
> I find The_ too much noise.

I used to be of the school of thought that a function name should be a
noun phrase (possibly including the name of the type being returned,
although this need not be rigorous).  But one inevitably bumps into this
very name clash: The tendency is to want to use the same noun for the
object receiving the result of the function.

My conclusion was to give up on trying to use pure noun phrases for
function names, and instead find a way to mark the function names. 
Booch seems to prefer using a dangling preposition that leads into the
parameters:

   function Parent_Of (Child : in Pointer_Type) return Pointer_Type;
   ...
   Parent : Pointer_Type := Parent_Of(Child);

But I've found this to be awkward sometimes, particularly when the
function has more than one parameter.  Is it necessarily the first
parameter that is the object of the preposition?  Sometimes the most
natural prepositional phrase in English wants a "secondary" parameter as
its prepositional object and not the "primary" (i.e. controlling)
parameter of the function, so you're forced into contortions just to
satisfy English.

An alternative that I've personally settled on is to give up on the
distinction between functions and procedures, and to simply use verb
phrases for all subprogram names.  This emphasizes to the reader that
there is always _something_ happening when you make a subprogram call,
and the programmer should keep in mind the cost of making the call. 
Even when it's a function without side effects, there is the cost of
whatever calculation or retrieval it's performing. And even if that cost
is inlined and optimized away, there is at least a hypothetical cost --
which might not be so hypothetical if there is a design change during
maintenance and the function must be implemented differently.

If no particular verb comes to mind, a function could just tack on
"Get_" as a default:

   function Get_Parent
     (Child : in Pointer_Type) return Pointer_Type;

   procedure Set_Parent
     (Child : in out Pointer_Type; Parent : in Pointer_Type);
   ...
   Parent : Pointer_Type := Get_Parent(Child);

Note that there is a nice symmetry between a procedure that sets a value
and a function that gets it.  This convention has some precedents in the
naming styles I've seen in code written in other languages, and I see no
reason to denigrate this.

> Often I use an abbreviation if the scope is
> very small, something like
> 
>    Parnt : constant xxx := Parent (K);
> 
> I know that some coders and some coding standards are allergic to
> abbreviations, but I don't mind short identifiers and abbreviations if
> they have a small local scope.

It's against my religion to give up on the "Thou shalt not abbreviate"
commandment so easily.  :-)  Where do you draw the line on what counts
as a "small" scope?  Small scopes can have a nasty tendency to grow with
time.

I mean, it's sort of like saying that it's bad to beat up somebody on a
crowded street, but it's okay to beat up your spouse as long as you do
it in the privacy of your own home... hmm, I was going to put a smiley
in there, but that's just not funny.

------------------------------------------------------------------------
Internet.Usenet.Put_Signature 
  (Name => "John G. Volan",  Home_Email => "johnvolan@sprintmail.com",
   Slogan => "Ada95: The World's *FIRST* International-Standard OOPL",
   Disclaimer => "These opinions were never defined, so using them " & 
     "would be erroneous...or is that just nondeterministic now? :-) ");
------------------------------------------------------------------------