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=0.7 required=5.0 tests=BAYES_00,INVALID_DATE,
	MSGID_SHORT,REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no
	version=3.4.4
Xref: utzoo comp.software-eng:1128 comp.lang.ada:2041
Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!uflorida!gatech!hubcap!billwolf
From: billwolf@hubcap.clemson.edu (William Thomas Wolfe,2847,)
Newsgroups: comp.software-eng,comp.lang.ada
Subject: Re: comments on comments on comments
Message-ID: <4534@hubcap.UUCP>
Date: 24 Feb 89 02:15:50 GMT
References: <419@serene.UUCP>
Sender: news@hubcap.UUCP
Reply-To: wtwolfe@hubcap.clemson.edu
List-Id: <comp.lang.ada>

>From article <419@serene.UUCP>, by rfarris@serene.UUCP (Rick Farris):
>> |Just follow the convention that when code is updated so are the
>> |comments.
> 
> Hmm.  That's ok when you're working on small projects.  I've never
> seen it work in real-life when many programmers were involved.

    I use a tactic which essentially makes comments as inherent a part
    of the code as possible: I make all package, procedure, function, 
    type, and variable names as descriptive as reasonably possible.

    Examples:

       procedure POSITION_AT_LAST_ITEM (SOME_LINKED_LIST);

       function ELIMINATE_LEADING_AND_TRAILING_SPACES (SOME_STRING);

       type SERIALIZABILITY_GRAPH; 

       package GENERIC_SIMPLE_DIRECTED_GRAPH;

       MENU_OPTIONS : MENU_HANDLER.LINKED_LIST;

    This allows me to essentially eliminate the need for many of the
    comments that I see in the code of other programmers.  It preserves
    my comment-writing patience for semantic descriptions of procedures,
    and for those situations in which I'm using sophisticated strategies
    to make an ADT implementation as fast as I can possibly get it which
    involve complex reasoning about the state of the ADT structure (and
    the variables used by the manipulating algorithms).  

    Also, I've learned to type very quickly, through long hard experience.  :=)


    Bill Wolfe, wtwolfe@hubcap.clemson.edu