Re: procedure parameter names

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