Re: procedure parameter names

[Rory Hewitt <rory.hewitt@xxxxxxxxx>]

Larry,

My responses:

1) I wouldn't hire anyone who couldn't figure out that RtnVal didn't mean
ReturnValue. Readability is good, but shorter names, in conjunction with
appropriate comments can be even better.

2. The use of long names often forces expressions to span multiple lines,
which can be harder to read (less usable).

As far as ContentAssist etc. goes, that's great *if you use WDSc and
ContentAssist*. If you don't, then long names are a real pain.

Personally, if I saw "rateEffDate" (ideally in conjunction with some general
program documentation and comments), I'd know what it was. If you'd care to
send me a list of shorter names, I'll have a stab at figuring them out - I'm
pretty sure anyone on these forums would do a very good job, even in the
absence of any context.

To me, the (over-)use of long variable names could equally signify that
those developers just don't like writing comments. I know, I know,
"self-documenting code" and all that. But is this

// Calculate rate effective date
if rateEffDate < currDate or rateEffDate >= prevEffDate;
  rateEffDate = currDate;
endif;

really worse than this:

if RateEffectiveDate < currentDate or
   RateEffectiveDate >= PreviousEffectiveDate;
  RateEffectiveDate = CurrentDate;
endif;

I'm an SEU user and I'm likely to stay that way.

Rory

p.s. "A slight but welcome over-compensation methinks - the compiler team
equivalent of buying a sports car at 40. ;-)" Hmmm. I bought my first
motorcycle at 38, so maybe I have some personal growth issues of my own ;-)

On Thu, May 20, 2010 at 3:09 AM, Larry Ducie <larry_ducie@xxxxxxxxxxx>wrote:

> Hi Charles,
>
> <snip>
> Your examples are perfect examples of such.  I don't think anybody on the
> list would have looked at RtnVal and read it any other way than ReturnValue.
> </snip>
>
> This is a very interesting and common reaction to questions of naming
> standards in RPG.
>
> We have suffered so long with short names that we have convinced ourselves
> that it is either a "good" thing or at least we can make a good thing out of
> it.
>
> It just simply isn't true. We have the ability to code long names for a
> very good reason - it makes life easier.
>
>
> For me there are two points to this:
>
> 1) Readability - Although you "don't think" anybody on the list would have
> looked at RtnVal and read it any other way than ReturnValue, I can GUARANTEE
> that only the intellectually challenged would look at ReturnValue and NOT
> read it as ReturnValue.
>
> 2) Usability - We write our variable, parameter, and procedure names as
> well as read them. The use of full and descriptive names removes the
> ambiguity out of its intended use and helps the developer to decide on a
> suitable name.
>
> Case in point: Variable - holds the Rate Effective Date, logically derived
> long descriptive name: RateEffectiveDate
> Possible other abbreviated variable names: rteeffdat, refdat, rateEffdat,
> rateEffDate, rteEffDate, etc...
>
> Although there are a very large number of variations of names available
> when abbreviating a variable name, there is one and only one long
> descriptive name.
> I am responsible for standards in our shop and our standards state clearly
> that a full descriptive name is required. In the case above, there really is
> only one name that every developer in our shop would arrive at when forced
> to use these standards - RateEffectiveDate.
>
> I also totally agree with Mihael. The use of Content Assist in WDSCi / RDi
> / RDP makes a nonsense of the short-is-quicker rule. Its actually quicker to
> use the long name because you start typing the long name and Content Assist
> helps complete it for you. When you are open to the seemingly-infinite
> variation of abbreviations I wouldn't know whether to start typing Rte,
> rate, ref, etc... This makes it MUCH HARDER to use Content Assist.
>
> Cheers
>
> Larry Ducie