Another aspect of comments and coding standards

Another aspect of comments and coding standards

[W. Wesley Groleau (Wes)]

Brief rehash of recent suggestions (not necessarily all compatible):

1. Coding standards should make code more readable.
2. Coding standards should facilitate re-use.
3. Coding standards can be used to add semantics to the language,
   thus reducing the need for comments.
4. Code should be understandable with neither the coding standard nor the LRM.
5. It's going to a silly extreme to expect code to be understandable
   without the LRM.
4. Anything that can be expressed in the language instead of in comments
   should be.
5. Comments should be used to express abstractions at a higher level.
6. Comments should be used when the code isn't clear.
7. The code should always be clear.

I didn't do that just to re-start the argument.  Rather, I seek opinions
on a related issue:

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.  :-)

---------------------------------------------------------------------------
W. Wesley Groleau (Wes)                                Office: 219-429-4923
Magnavox - Mail Stop 10-40                               Home: 219-471-7206
Fort Wayne,  IN   46808              elm (Unix): wwgrol@pseserv3.fw.hac.com
---------------------------------------------------------------------------

Re: Another aspect of comments and coding standards

[Robert Dewar]

Dave Marshall says

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

This is a very good point, particularly applicable to the case of
enumeration types. A weakness in Ada is that enumeration types are
always ordered, and you cannot hide this ordering from a client.

Logically what is often done is to arrange a set of enumeration values
in order so that subtypes dfining appropriate subclasses
can be defined as part of the same abstraction.

However, there is no way, other than coding standards, to avoid a client
noticing that today three values happen to be contiguous and replacing

   if a = enum1 or a = enum2 or a = enum3 then

by

   if a in enum1 .. enum3 then

Now of course you have a maintenance headache, because at the abstraction
level the specific order of the enumeration literals was not defined.
A reasonable coding standard is to absolutely forbid ranges in membership
tests for enumeration types (there is no similar objection for integer
types, this comment applies only to enumeration types).

Re: Another aspect of comments and coding standards

[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