Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!usc!elroy.jpl.nasa.gov!decwrl!netcomsv!jls
From: jls@netcom.COM (Jim Showalter)
Newsgroups: comp.object
Subject: Re: Functions without side effects (was Old confusion)
Keywords: method name
Message-ID: <1991Jun19.173144.6393@netcom.COM>
Date: 19 Jun 91 17:31:44 GMT
References: <130242@tut.cis.ohio-state.edu> <4888@osc.COM> <72893@microsoft.UUCP> <4116@ssc-bee.ssc-vax.UUCP> <4907@osc.COM>
Organization: Netcom - Online Communication Services  UNIX System {408 241-9760 guest}
Lines: 45

>If the arguments are classes, you may not need any clarifying nouns.  But in
>many cases the arguments are `int' or `const char*', and here it may not be
>immediately clear just what that integer is supposed to be.

In languages that have formal names for parameters, not just types, you can
use the formal names to self-document what all the mystery-int's are. For
example, in Ada (I'm using Ada here because it's the language I'm most fluent
in--yes, I realize other languages have this capability), you could write
things like:

    procedure Print (This_Many_Lines : in Integer);

The formal name "This_Many_Lines" eliminates any confusion about what
the Integer argument might specify.

For languages that have this capability, there is a nice additional
feature that makes a natural companion to formal parameter names--named
parameter association. In Ada, you could call the above procedure like
this:

    Print (This_Many_Lines => 8);

Note how this makes the code inherently self-documenting, always a noble
goal. Contrast this with:

    Print (8);

Which is the only argument binding syntax available in less readable
languages--from the above the reader cannot deduce whether the Print
is going to print the numeral 8, or eight of something, or what. And
off the the comments and/or documentation the maintainer runs where,
if he/she is lucky, the necessary information MIGHT be available. I
much prefer to put the requisite information into the code itself,
since that's the only way I can guarantee that the documentation
for the code and the code itself will stay in sync with one another.

Now, I get complaints occasionally that the version using named
parameter association is too verbose. I've noticed that such complaints
typically come from hunt-and-peck typists with little or no background
in maintenance, which pretty much says it all...
-- 
*** LIMITLESS SOFTWARE, Inc: Jim Showalter, jls@netcom.com, (408) 243-0630 ****
*Proven solutions to software problems. Consulting and training on all aspects*
*of software development. Management/process/methodology. Architecture/design/*
*reuse. Quality/productivity. Risk reduction. EFFECTIVE OO usage. Ada/C++.    *