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
X-Google-Thread: 103376,e94a7e4f6f888766
X-Google-Attributes: gid103376,public
From: Michel DELARCHE <delarche@cybercable.fr>
Subject: Re: Self-referential types
Date: 1999/10/24
Message-ID: <38130F67.C211C87D@cybercable.fr>#1/1
X-Deja-AN: 539928968
Content-Transfer-Encoding: 8bit
References: <7ttb4a$8mq$1@nnrp1.deja.com> <s04ql7cqh1s45@corp.supernews.com>
 <3802f2db_2@news1.prserv.net> <3803B5E3.F96A6DD4@mitre.org>
 <3803c8bc_2@news1.prserv.net> <3804E7E0.6A0265FB@mitre.org>
 <Pine.BSF.4.10.9910132009020.18305-100000@shell5.ba.best.com>
 <38077EB3.E6911567@mitre.org> <slrn80fl9f.68j.aidan@skinner.demon.co.uk>
 <380CA5AC.82499FE2@ftw.rsc.raytheon.com> <7um9ji$dor$1@nnrp1.deja.com>
 <7uq8vo$9gs$1@nntp6.atl.mindspring.net>
To: Richard D Riehle <laoXhai@ix.netcom.com>
X-Accept-Language: fr
Content-Type: text/plain; charset=iso-8859-1
X-Complaints-To: usenet@oceanite.cybercable.fr
X-Trace: oceanite.cybercable.fr 940769587 4335 212.198.22.50 (24 Oct 1999
 12:53:07 GMT)
Organization: Cybercable Paris NewsServer
Mime-Version: 1.0
NNTP-Posting-Date: 24 Oct 1999 12:53:07 GMT
Newsgroups: comp.lang.ada
Date: 1999-10-24T12:53:07+00:00
List-Id: <comp.lang.ada>

A telling anecdote about name-based vs. comment-based "clarity": in one
of my previous lives I was part of a team developing Fortran software
with the 8-character limitations in names etc. ; one variable that would
read CAPENDEG (an easily understandable French abbreviation for
"Heading-in-degrees") would not need any additional comment, either on a
stand-alone basis or by means of reference to previous specification
documents. The nag is that neither the military airmen writing the high
level specifications with the "obvious" assumption that they were
talking about magnetic headings nor the software engineers who were
developing the software with the (not less "obvious") assumption that
they were dealing with geographic headings, realised the
misunderstanding until the first mapped  trajectories came out of the
system, looking slightly tilted to the trained eyes of the aviators.
Both groups realised then that both the initial specifications and the
subsequent software implementation had missed something. More expressive
languages like Ada might have defined a more strict (sub)type and even a
unit system (cf. the recent thread on the Mars Orbiter crash), but I'm
still not sure that the "obvious" distinction between magnetic and
geographic heading would have popped up earlier that it did.

Based on my (past) experience of software development for a variety of
application fields, I think that the main problem with software
documentation integrity and maintainability is precisely that kind of
diverging implicit assumptions made by dedicated yet necessarily rather
narrowly trained professionals that fail to realise that what is
"obvious" to them may not be so "obvious" to someone else.

Richard D Riehle a �crit :

> In article <7um9ji$dor$1@nnrp1.deja.com>,
>         Robert Dewar <robert_dewar@my-deja.com> wrote:
>
> >My own view is that good names are an *adjunct* to good
> >comments, not a substitute for them.
>
> Many software products developed in Ada are based on some
> larger systems engineering specification.  The software must
> reflect the constraints of that specification.  For example,
> in one communications satellite software effort, it was common
> to see comments that referred back to a paragraph of the
> engineering specification.
>
> It would have been quite foolhardy to rely only on the names of
> the entities.   Many of these names described some complicated
> calculation that could only be understood by looking at the
> underlying mathematics in the engineering specification.  For
> trivial programs in which one is simply getting and putting
> data to and from files, meaningful names might be enough. For
> serious engineering applications, we need comments that correspond
> to the original specification.
>
> As usual, we use the kind of tools appropriate for the problem
> space and solution space.  I am beginning to think that people who
> make up hard and fast rules for computer programming are people who
> no longer actually write programs.  Perhaps they never did.
>
> Richard Riehle
> http://www.adaworks.com
>