Re: Another aspect of comments and coding standards

[dmarshal@netcom.com (Dave Marshall)]

"W. Wesley Groleau (Wes)" <wwgrol@PSESERV3.FW.HAC.COM> writes:

>When does using a language feature become a "clever trick" to be avoided?

>What is the threshold between (1) keeping the actual code simple but not clear
>(and filling in with comments) and (2) allowing complexity of code to
>eliminate the need for those comments?

>For example, which is better and why:

>   if Value in Limit_1 .. Limit_2 then         if Limit_2 >= Limit_1 and
>      -- note possibility of null range           Value   >= Limit_1 and
>      -- [ see LRM 3.5(4) & 4.5.2(27-32) ]        Value   <= Limit_2   then

>Examples with other language features also welcome.

>I'm withholding my opinion lest those who agree keep silent.  :-)

Well, first, if you're holding up membership tests as a "clever
trick," then we're all doomed.

Secondly, regarding your examples:  I would hope that no one in his
right mind would be inserting LRM references in his code.  One
shudders to think about how one might be looking through pages and
pages of comments looking for the occasional statement.

[Before I go on, the little critic in me wants to point out that if
Value >= Limit_1 and Value <= Limit_2, then we know that Limit_2 >=
Limit_2, so your second example has a redundancy.]

In the abstract, I prefer the first example (without the LRM comments,
of course).  I don't regard this as a clever trick in the slightest,
given that it's got several paragraphs devoted to it in the LRM.  If
someone looking at this code in the future doesn't immediately
recognize this as a membership test (and where to go look in the LRM
if necessary), he should find other employment.

In other words, every instance of source code shouldn't be expected to
provide tutorial information for inexperienced programmers.

That having been said, let me address the issue of context in which
such a "clever trick" appears.  This would apply to almost every
clever trick used, so my continued use of the membership test
shouldn't be construed to mean that I think these remarks are limited
to membership tests.

With a little bit of effort, we can usually make "clever tricks" very
readable and understandable.

For instance, I am a little bit uncomfortable with the use of the
anonymous subtype used in the membership test.  I'd rather see

Some_Block_Name:
declare

   subtype Legal_Values is Some_Type range Limit_1 .. Limit_2;

begin

   if Value in Legal_Values then
      ...
   end if;

end Some_Block_Name;

By choosing appropriate names, we can make what's going on clear to
even the most dense.

Furthermore, we might choose to hide our clever tricks within the
abstraction we're implementing.  For instance (and I agree this is
crude, but I hope it illustrates my point):

Instead of:

High_Limit := Float(220 - Age) * 0.85;
Low_Limit  := Float(220 - Age) * 0.75;

if Heartbeat in Integer(Low_Limit) .. Integer(High_Limit) then
   Do_Something;
end if;

we might have

if Is_Aerobic(Pulse => Heartbeat,
              Age   => My_Age) then
   Do_Something;
end if;

-- 
Dave Marshall
dmarshal@netcom.com