From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=-1.3 required=5.0 tests=BAYES_00,INVALID_MSGID
	autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,5e12faea1fbd9314,start
X-Google-Attributes: gid103376,public
From: "W. Wesley Groleau (Wes)" <wwgrol@PSESERV3.FW.HAC.COM>
Subject: Another aspect of comments and coding standards
Date: 1996/06/06
Message-ID: <9606061336.AA03923@most>#1/1
X-Deja-AN: 158776762
sender: Ada programming language <INFO-ADA@LISTSERV.NODAK.EDU>
comments: To: info-ada%listserv.nodak.edu@vm1.nodak.edu
mailer: Elm [revision: 70.85]
newsgroups: comp.lang.ada
Date: 1996-06-06T00:00:00+00:00
List-Id: <comp.lang.ada>


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
---------------------------------------------------------------------------