Re: comments on comments

Re: comments on comments

[Bob Hathaway]

Dave Jones [djones@megatest.UUCP] Writes:
>Here are some remarks that I wrote up for one of the
>members of my programming team.  I hope they will be
>helpful.

Thanks, I agree good documentation is invaluable.

>
>In my opinion, the most important parts of a program to document
>are the structure-declarations and the variable-declarations.
>

This is true, but alternate design strategies can call for an
extended perspective on documentation.  When using an object
oriented design strategy, I'll first write a design document
describing the primary objects in the system and their operations.
Also in the document will be a high-level description of the
important procedures written in an informal PDL, such as a pseudo
Ada code.  For objects (Adts), first is a description of the object and
its rational and system context.  For instance, what the object is
intended for, why I chose an abstract data object or an abstract data
type, and possibly how it will interact in the system, but
the last part could go in a separate document as pointed out
by Dave Jones.  Second is a numbered list of operations and their 
descriptions.   When the entire system is complete, the declarations
can be coded in a higher-order language.  In Ada, the design is directly
implementable as compilable specifications.  In Modula or some other
language in which the specifications aren't compilable the procedures
can be filled in with stubs or empty declarations.  The design document
can be included as comments and updates to the document and code should
be done concurrently.  The object descriptions are included in the
specifications and optionally in the package or module body, and the
(numbered) operation descriptions included for each procedure or method.

>Here's a good way to go about it:
>
>/*******************************
> * This is one block comment,
> * and it is easy to modify.
> ******************************/
>

Here's another way:

/*
 * my_procedure
 *
 *    <ADT design document index>
 *    This is a description of...
 *    ...
 */

             Bob Hathaway
             rjh@purdue.edu

Re: comments on comments

[Bob Hathaway]

(I write)
>|This seems to go backwards.  Programmers should first design
>|their software then implement it.  You seem to be advocating 
>|implementation then design.  The descriptive algorithm should 
>|come first, then the code.

In article <9689@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes:
>I have a problem with Top-Down programming (design then
>implementation); it happens to be the same problem I have with
>Bottom-Up programming (implementation then design).  You so eloquently
>point it out in your next sentence:  

Design then implementation is not necessarily top-down programming.
First some terminology.  Top-down design involves a functional view
starting at the top and working its way down.  Top-down implementation
is a programming methodology which begins coding (implementing the design)
at the top level procedures.   Bottom-up design also involves a 
functional (procedural) view but starts design with the bottom level
procedures and bottom-up implementation begins coding with the bottom
level procedures.  For the past several years (since my first program)
I began with an Adt, or more object oriented approach to design and
implementation.  I would study the problem and form an informal solution
and identify the Adts (objects in the system).  The informal solution
would be in a high level pseudo-code and was usually top-down for the
main program and within modules.  This provided a modular design with
abstract data types.  It could also be categorized as a top down design
with the data structures and functionally related subprogram units
encapsulated within modules.  The Adts provided an excellent starting point
for coding.  They could be separately tested and frequently the driver
program for these tests was most conveniently the original program and
after "testing" my Adts the program was finished.  The fact that I was
often done weeks early attested to the techniques success.  The informal
pseudo-code is refined into working code but since pseudo-code usually
offers a more informal description of an algorithm than working code,
it is easier to understand.

>|If the algorithm can be coded in a
>|truly self descriptive form no comments will be necessary but in
>|instances where the design and implementation are not the same,
>|comments help.

>But design and implementation should not differ!  If this is happening,
>one of the two is wrong!  In the case of Top-Down, I would guess that
>it is probably the design that is wrong; something wasn't taken into
>account until someone actually tried to implement the design.  The

I disagree.  Pseudo-code is much easier to read than programming code.
Comments reflect algorithms in an informal way that is more understandable
than programming code.  They are semantically equivalent, but if I think an
informal description is easier to read, I'll provide it (you can put me in
the conscientious category of programmer who is always trying to write better
software).  When an algorithm can be directly expressed in code (ie. just add
underscores) as is often the case, comments aren't necessary.

>problem with Top-Down (and Bottom-Up) programming is that there is no
>feedback mechanism.  What happens when an implementation discovers a
>bug in a design?  Does it happen that people go back and formally
>re-review an already approved design document?  Not nearly as often as
>it should, I suspect.  Or at least go back and change the design to
>match the implementation?  It gets even worse when there are many
>levels to the design.  There needs to be a feedback loop.

Any conscientious programmer will update the appropriate documents.  But
if put on a system where the comments are in doubt, I can always ignore
them.  When working with large C programs, I often waste a lot of time
trying to understand undocumented field declarations and incomplete function 
descriptions.  A correct comment would save time and it should be obvious
from the code if a comment isn't accurate.  As suggested in an earlier
article, large software projects with elaborate standards can hold design and
code reviews to insure correctness.

>|True, but requiring Joe Programmer to design his software first will help,
>|and the design can be included in the comments.

>Yes, but until we have good hypertext systems that will allow Joe
>Programmer to do this easily and painlessly, he basically has to
>maintain TWO design documents, and when a human being has to do it, it
>tends to get out of sync, and eventually useless.

Yes, thats why there are software development environments and APSE's and why
I keep asking for them:-)

|I think the poorly designed, poorly documented systems have caused most
|of the trouble, not out-of-date commenting.   Just follow the convention
|that when code is updated so are the comments.  The benefits of a well
|commented design far outweigh the costs.  Well documented code is easy
|to understand and modifications to the software can be done in terms of
|the higher-level design.  Since the design is directly implemented in the
|code, corresponding changes should be easy.

> The real question is:  what can we do to make this happen?

Be conscientious!

Bob Hathaway
rjh@purdue.edu

Re: comments on comments

[Dave Jones]

In an article by rjh@cs.purdue.EDU, Bob Hathaway says that he usually
uses ADT's to do top-down design and implementation...

If it works for him, that's great.

I too have been designing all my programs around "abstract data-types"
for some time now, although not since my first program, as he has. 
I started programming for bucks back in '71, when we didn't think of 
such things.  Indeed, I sort of evolved into the practice years later
as a result of much head-scratching. Only afterwards did I discover that
I was not the only one to have dreamed up the technique.

But I don't usually do top-down.  I do bottom-up.  Design, implementation,
test, everything.  It actually shocks some people when I say that. In the
seventies "bottom-up" became a dirty word.  Never mind that top-down
methods resulted in some of the most inflexible code every put to disk.
Top-down good. Bottom-up bad. Unnngghh. :-)

I'll freely admit, there are times when top-down is the way to go.  But
it's not the way I do most of the programs I write by myself.

I start out with a "bottom" that consists of lots of -- okay, I'll go 
along with the name -- ADT's which are likely to be of use in just 
about any kind of program: lists, queues, hash-tables, avl-trees, 
flexible buffers, priority queues and so on.  Next I use these to form 
ADT's which are specific to the low-level objects under consideration, 
etc.  And so it goes from bottom to top.  The payoff comes when you want
to change something. All you have to do is reshuffle these building blocks,
which are still quite useful. But if you go from the top to the bottom, 
a change at the top is likely to invalidate the whole blasted thing.

I sometimes carry it to unlikely extremes.   My group is writing a Pascal 
compiler. If ever there seemed to be a top-down kind of task, that seemed to be
it.  I mean, Pascal is already done, for Pete's sake.  There are standards
documents which tell you what a Pascal compiler absolutely *has* to do. But..
I started out with my bag of standard ADT's anyway, and then defined some
more: Pascal blocks, types, parms, variable-accesses...  just about
every kind of Pascal-object you can think of.  One by one we implemented
them as we worked our way up to type-definitions, expression-trees, statements.
The methods for these ADT's went into a library.

It was only a matter of a few weeks, long before the compiler's high level 
was anywhere near finished, that it paid off.  Another group was doing 
a mouse-driven frontend for the interactive embedded compile/load/go
feature that we have.  They needed to be able to capture all of the 
type-information, formal parameters and so forth about the program being 
run, then fish around in it finding all the variables of this type, 
building all the short expressions that are assignment compatible to the 
second formal parm of procedure foo, etc..   

No problemo.  

Just link with the new Pascal-compiler-library and do yo thang! 
I was psyched.

Try doing that with a Pascal compiler that was designed top-down to
be a Pascal compiler.

Good Design Strategies <Was comments on comments>

[Bob Hathaway]

In article <2325@goofy.megatest.UUCP>, djones@megatest.UUCP (Dave Jones) writes:
> In an article by rjh@cs.purdue.EDU, Bob Hathaway says that he usually
> uses ADT's to do top-down design and implementation...

Umm, the method presented was better categorized as a modular design
strategy with abstract data types.  The implementation strategy was
Adt/object oriented because coding began by implementing the Adts.  In 
top-down/bottom-up terminology this corresponds to top-down design with
bottom-up implementation.  This strategy can be applied recursively
to Adts with the top level object as the starting point in design
and the bottom level sub-objects as the starting points in implementation.
We know that we need an intermediate code Adt, which may require a generic
tree Adt, which may require a generic list Adt, and so on.  It seems
natural to first identify the intermediate code Adt as necessary in the
overall system design but to begin its implementation at the bottom level
by using generic components.

Since the following is long, I'll ask here.  It would be interesting to see
some discussion on design strategies; any interesting opinions or experiences?

> I too have been designing all my programs around "abstract data-types"
...
> But I don't usually do top-down.  I do bottom-up.  Design, implementation,
> test, everything.  It actually shocks some people when I say that. In the
> seventies "bottom-up" became a dirty word.  Never mind that top-down
> methods resulted in some of the most inflexible code every put to disk.
> Top-down good. Bottom-up bad. Unnngghh. :-)

What you describe sounds like an Adt/object oriented implementation, I'm not
sure if the bottom-up arguments apply.

> I'll freely admit, there are times when top-down is the way to go.  But
> it's not the way I do most of the programs I write by myself.
> 
> I start out with a "bottom" that consists of lots of -- okay, I'll go 
> along with the name -- ADT's which are likely to be of use in just 
> about any kind of program: lists, queues, hash-tables, avl-trees, 
> flexible buffers, priority queues and so on.  Next I use these to form 
> ADT's which are specific to the low-level objects under consideration, 
> etc.  And so it goes from bottom to top.  The payoff comes when you want
> to change something. All you have to do is reshuffle these building blocks,
> which are still quite useful. But if you go from the top to the bottom, 
> a change at the top is likely to invalidate the whole blasted thing.

The standard argument for top-down design is that design errors are caught
early.  A top level change could make all the work done at the bottom level
unnecessary and major rewriting or complete scrapping could occur.  That
is the advantage of top-down design with bottom-up implementation, the
overall design should be close to correct and the implementation is direct
and fast because the objects and procedures don't depend on anything not
yet implemented.  I think the advantage of "building blocks" should be
evident in any design since code which is designed to be easy to modify
will consist of reusable and parameterized components which correspond
to a loosly coupled and highly cohesive modular design.

> I sometimes carry it to unlikely extremes.   My group is writing a Pascal 
> compiler. If ever there seemed to be a top-down kind of task, that seemed to be
> it.  I mean, Pascal is already done, for Pete's sake.  There are standards
> documents which tell you what a Pascal compiler absolutely *has* to do. But..
> I started out with my bag of standard ADT's anyway, and then defined some
> more: Pascal blocks, types, parms, variable-accesses...  just about
> every kind of Pascal-object you can think of.  One by one we implemented
> them as we worked our way up to type-definitions, expression-trees, statements.
> The methods for these ADT's went into a library.
> 

This sounds like a bottom-up implementation, but since the upper levels
(objects) were already known in advance, a top-down design (loosly speaking).

>It was only a matter of a few weeks, long before the compiler's high level
>was anywhere near finished, that it paid off.  Another group was doing
>a mouse-driven frontend for the interactive embedded compile/load/go
>feature that we have.  They needed to be able to capture all of the
>type-information, formal parameters and so forth about the program being
>run, then fish around in it finding all the variables of this type,
>building all the short expressions that are assignment compatible to the
>second formal parm of procedure foo, etc..
>...
>
>Try doing that with a Pascal compiler that was designed top-down to
>be a Pascal compiler.

It sounds like the bottom-up implementation provided them with the working
software early.  A good design will provide reusable components which are
easy to modify regardless of the implementation.

Bob Hathaway
rjh@purdue.edu

Re: Good Design Strategies <Was comments on comments>

[Dave Jones]

From article <6100@medusa.cs.purdue.edu>, by rjh@cs.purdue.EDU (Bob Hathaway):
> 
> The standard argument for top-down design is that design errors are caught
> early.  A top level change could make all the work done at the bottom level
> unnecessary and major rewriting or complete scrapping could occur.  That
> is the advantage of top-down design with bottom-up implementation, the
> overall design should be close to correct and the implementation is direct
> and fast because the objects and procedures don't depend on anything not
> yet implemented.  I think the advantage of "building blocks" should be
> evident in any design since code which is designed to be easy to modify
> will consist of reusable and parameterized components which correspond
> to a loosly coupled and highly cohesive modular design.
> 

If you end up with "reusable and parameterized components ... loosely
coupled... modular", then it doesn't matter how you got there.
My argument is that in most cases, you are more likely to end up
in such a software ecstacy if you use bottom-up design techniques,
and you'll get there quicker.

The argument for top-down design is based on some assumptions that are 
seldom met.  If the project has these properties, top-down design
can be the best order of business.

   1. Design and implementation are distinct and separate activities.

      If they are not, you can't do one from one direction, and the
      other from the other direction.

   2. A "correct design" can be identified without benefit of prototyping,
      and it will inevitably be error free.


You say, "A top level change could make all the work done at the bottom level
unnecessary and major rewriting or complete scrapping could occur."

HATE IT when that happens!  

That is one reason why I design the low-level objects first.  If they are 
designed without knowledge of the specifics of the higher levels, high 
level changes cannot effect them.  The disaster happens when somebody 
"finishes" the high level design and then designs the bottom level around 
that, and then Ooops! -- it turns out that the high level design had a flaw
in it. Then you discover that the change propogates right down through
all the levels.

Or maybe somebody thinks up an entirely different kind of top-end that 
deals with the same kinds of objects.  Either way, you are likely SOL 
because those low level routines knew too much for their own good.  Now 
if the design at the low level is good, all is well.  Like I said, if you
get there, it doesn't much matter how you got there. But which technique
is less error-prone?

I gave a case history of using the parts of a Pascal compiler in
a mouse-clicky kind of editor. I'll reply to one comment.
You said, "It sounds like the bottom-up implementation provided them 
with the working software early."

I say, The bottom-up design provided them with software that didn't
"know it was in a compiler".  Recall, I did not even know about that
project when I started the compiler. 

And I meant it literally when I said, "Try doing that with a Pascal
compiler that was designed top-down to be a Pascal compiler."

Actually try it.  

I have tried to use the parts of other production compilers
to do things other than pre-runtime compilation. Not as an academic
exercise, but to produce real commercial products.  That's why I'm
writing this one!  I would rather buy the source for one off the self.
Better yet, what I would really like is what I am writing: a library of
low and mid level Pascal object Adt's. Then I wouldn't even need the 
source, except to fix bugs and port it to new platforms. But try to
find such a thing: an open architecture compiler.  So far as I know, I 
am writing the first one.

Re: Good Design Strategies <Was comments on comments>

[Rob Jellinghaus]

In article <2344@goofy.megatest.UUCP> djones@megatest.UUCP (Dave Jones) writes:
>From article <6100@medusa.cs.purdue.edu>, by rjh@cs.purdue.EDU (Bob Hathaway):
>> The standard argument for top-down design is that design errors are caught
>> early.  A top level change could make all the work done at the bottom level
>> unnecessary and major rewriting or complete scrapping could occur.  That
>> is the advantage of top-down design with bottom-up implementation, the
>> overall design should be close to correct and the implementation is direct
>> and fast because the objects and procedures don't depend on anything not
>> yet implemented.  I think the advantage of "building blocks" should be
>> evident in any design since code which is designed to be easy to modify
>> will consist of reusable and parameterized components which correspond
>> to a loosly coupled and highly cohesive modular design.
>
>If you end up with "reusable and parameterized components ... loosely
>coupled... modular", then it doesn't matter how you got there.
>My argument is that in most cases, you are more likely to end up
>in such a software ecstacy if you use bottom-up design techniques,
>and you'll get there quicker.

Everyone involved in this discussion should get their hands on a copy
of Bertrand Meyer's book _Object-Oriented Software Construction_, Prentice-
Hall, 1988.  The design philosophy being discussed sounds virtually
identical to Meyer's exposition of the object-oriented design method.

Briefly, Meyer's summary of object-oriented design is as follows:

	Ask not what the system does, ask what it does it to.

In other words, the most important characteristic of the system is NOT
its overall "intended function".  The most important description of the
system is in terms of the objects, the data, that is manipulated by the
system.

This is more akin to bottom-up design than to top-down design, for sure,
although the emphasis is slightly different.

>You say, "A top level change could make all the work done at the bottom level
>unnecessary and major rewriting or complete scrapping could occur."
>
>HATE IT when that happens!
>
>That is one reason why I design the low-level objects first.  If they are
>designed without knowledge of the specifics of the higher levels, high
>level changes cannot effect them.  The disaster happens when somebody
>"finishes" the high level design and then designs the bottom level around
>that, and then Ooops! -- it turns out that the high level design had a flaw
>in it. Then you discover that the change propogates right down through
>all the levels.

The typical top-down design spec is functionally oriented; i.e. "We want
the system to Do This, and in order to Do It, it'll have to do this, and
this, and this..." etc., etc.  When you change your mind about what you
want it to Do, you're hosed.  Object-oriented style avoids this, by focusing
the design effort on the structure of the data to be handled, rather than
on the design of the whole system.  A proper object-oriented design is
inherently modular, and seldom needs a complete revision; the modules are
organized in a network rather than in a hierarchical tree, which means
changes to the net can be made without affecting the whole system; whereas
if you need to change the root of a top-down tree, you're hosed.

>I gave a case history of using the parts of a Pascal compiler in
>a mouse-clicky kind of editor. I'll reply to one comment.
>You said, "It sounds like the bottom-up implementation provided them
>with the working software early."
>
>I say, The bottom-up design provided them with software that didn't
>"know it was in a compiler".  Recall, I did not even know about that
>project when I started the compiler.

Exactly.  Your objects were general enough to be free from a specific
system.  This is reusability, and Meyer talks about how to get it.  A lot.

>I have tried to use the parts of other production compilers
>to do things other than pre-runtime compilation. Not as an academic
>exercise, but to produce real commercial products.  That's why I'm
>writing this one!  I would rather buy the source for one off the self.
>Better yet, what I would really like is what I am writing: a library of
>low and mid level Pascal object Adt's. Then I wouldn't even need the
>source, except to fix bugs and port it to new platforms. But try to
>find such a thing: an open architecture compiler.  So far as I know, I
>am writing the first one.

You should definitely go out and take a look at this book.  One of Eiffel's
(Meyer's language) main selling points is its reusable object library,
with everything from arrays to hash tables to an Xwindows library already
coded.  (According to reports, lexical analysis and (someday) concurrency
libraries will be available too.)  Sounds right up your alley!

Rob Jellinghaus                | "Next time you see a lie being spread or a
jellinghaus-robert@CS.Yale.EDU |  bad decision being made out of sheer ignor-
ROBERTJ@{yalecs,yalevm}.BITNET |  ance, pause, and think of hypertext."
{everyone}!decvax!yale!robertj |     -- K. Eric Drexler, _Engines of Creation_

Re: Good Design Strategies <Was comments on comments>

[William Thomas Wolfe,2847,]

From article <51955@yale-celray.yale.UUCP>, by jellinghaus-robert@CS.YALE.EDU (Rob Jellinghaus):
> Everyone involved in this discussion should get their hands on a copy
> of Bertrand Meyer's book _Object-Oriented Software Construction_, Prentice-
> Hall, 1988.  The design philosophy being discussed sounds virtually
> identical to Meyer's exposition of the object-oriented design method.

    I'd suggest Booch's coverage of object-oriented design in
    "Software Components with Ada" instead; Meyer's book comes
    bound up with a rather flaky programming language.

> You should definitely go out and take a look at this book.  One of Eiffel's
> (Meyer's language) main selling points is its reusable object library,
> with everything from arrays to hash tables to an Xwindows library already
> coded.  (According to reports, lexical analysis and (someday) concurrency
> libraries will be available too.)  

    Ada has far more reuseable ADTs already coded.  I'm coding a concurrent
    ADT right now, in fact.  Vendors such as EVB, lib systems, Wizard Software,
    and so on, have entire catalogs of Ada components you can buy right off the
    shelf, and Ada's rigorous standardization ensures that they'll compile
    anywhere.  Booch's other book, "Software Engineering with Ada" is also 
    worth reading, and I think it also contains something on object-oriented 
    design.  ("Software Components" is more of an advanced text)

    Also, one can obtain a magtape copy of the Ada Software Repository from

        MACA
        Attn: Janet Mckellar
        P.O. Drawer 100 - Bldg T148
        White Sands Missile Rang, NM  88002

    It fills up an entire magtape at 6250 bpi in tar format, and costs
    essentially nothing; all they need is your magtape and enough postage 
    to get it back to you.

    The Ada Information Clearinghouse Newsletter periodically summarizes major
    Ada software libraries and systems; it's free, and you can get on the
    mailing list by sending a postcard to 

        Ada Information Clearinghouse
        c/o IIT Research Institute
        4600 Forbes Blvd., Second Floor
        Lanham, MD  20706-4312
 
    Also, the recent issue of ACM SIGADA Ada Letters contains several
    interesting articles on ADT design and object-oriented programming.  


    Bill Wolfe, wtwolfe@hubcap.clemson.edu
    comp.sw.components Mailing List administrator 

Re: Good Design Strategies <Was comments on comments>

[John Baugh]

In article <4571@hubcap.UUCP> wtwolfe@hubcap.clemson.edu writes:
>From article <51955@yale-celray.yale.UUCP>, by 
>            jellinghaus-robert@CS.YALE.EDU (Rob Jellinghaus):
>> Everyone involved in this discussion should get their hands on a copy
>> of Bertrand Meyer's book _Object-Oriented Software Construction_, ...
>>   [discussion of decomposition methods deleted]
>    I'd suggest Booch's coverage of object-oriented design in
>    "Software Components with Ada" instead; ...

IMHO, these ideas were more clearly expressed by people like
Parnas and Liskov back in the 70's.  For instance:

  D. Parnas, "On the criteria to be used in decomposing systems into 
      modules," CACM, v15, Dec. 1972.

and more recently:

  B. Liskov and J. Guttag, _Abstraction_and_Specification_in_Program_
      _Development_, MIT Press and McGraw Hill, 1986.

Of course, the phrases "information hiding" and "ADT" don't sound 
as high-tech as "object-oriented" :-)  (Comments about polymorphism
and inheritance unnecessary, and flames to /dev/null.).

John Baugh
-- 

Re: Reuseable Ada components

[William Thomas Wolfe,2847,]

   [Karl Nyberg e-mailed me some information regarding my recent 
    article, which I believe to be of general interest...]  

From: karl@grebyn.com (Karl Nyberg)
Organization: Grebyn Corporation
Phone: +1 703 281 2104

>    Ada has far more reuseable ADTs already coded.  I'm coding a concurrent
>    ADT right now, in fact.  Vendors such as EVB, lib systems, Wizard
>    Software, and so on, have entire catalogs of Ada components you can buy

That's pretty good.  You only missed about another half dozen to ten
vendors.

   [Editor's note: I did say "and so on"...]

>    Also, one can obtain a magtape copy of the Ada Software Repository from
>
>        MACA
>        Attn: Janet Mckellar
>        P.O. Drawer 100 - Bldg T148
>        White Sands Missile Rang, NM  88002

About ten other people also provide this service.  Differing formats are
supported by others for varying fees.  Folks on the arpanet can get it via
anonymous FTP. 

>    The Ada Information Clearinghouse Newsletter periodically summarizes major
>    Ada software libraries and systems; it's free, and you can get on the
>    mailing list by sending a postcard to 
>
>        Ada Information Clearinghouse
>        c/o IIT Research Institute
>        4600 Forbes Blvd., Second Floor
>        Lanham, MD  20706-4312

As does my newsletter and recent book.  In case you missed the Jan/Feb Ada
Letters issue in which a draft of this review was printed:

==================================================================

Ada: Sources and Resources, 1989 Edition
  by Karl A. Nyberg

A Capsule Review by Dave Emery

At one time or another, most of us have served as "resource people"
for our companies on Ada.  Ada: Sources and Resources serves as a
single point for answering most of those non-technical "I have an Ada
question" phone calls that we seem to get.  Karl Nyberg has collected
information on vendors, organizations, publications and conferences,
and other related sources of Ada information, and placed it all into a
single volume.

The book starts off with a capsule history (presented chronologically)
of the Ada program.  This is particularly useful for documenting the
order of events in the history of Ada. (Which came first, the ACVC
contract or the Preliminary Ada reference manual?)  The remaining
chapters cover compiler vendors, software tool vendors, groups and
organizations (both government and private), publications, electronic
services, consultants and trainers, conferences, professional
recruiters, books and finally a glossary of terms and acronyms.  Each
chapter covers the material alphabetically, with extensive
cross-referencing.

The best entries in the book include historical information on the
vendor or organization, as well as information on the product or
service provided.  The entries always include a point of contact.
Some entries are not as complete as others, and this lack of
consistency is one of the book's few shortcomings.

In his forward, Bob Mathis compares the book to a well-stocked
Rolodex.  This book has a tremendous advantage over a Rolodex, namely
the comprehensive indexes.  There are separate indexes for names of
individuals (points of contact), "items" (proper names, such as ACEC
and VADS), vendors, and organizations.  It would be nice if there
were an index to compilers and tools by computer, to answer questions
like "What tools run on a Sun?"

This is a valuable book.  I had a pre-publication draft that saved me
a lot of time going through back issues of Ada Letters and sales
brochures to find the name of a particular vendor or organizational
contact.  It deserves a place right next to your telephone, either to
answer questions, or to call someone to get an answer.

==================================================================

   [I have deleted Karl's standard advertising blurb]

Karl A. Nyberg          karl@grebyn.com, nyberg@ajpo.sei.cmu.edu
Grebyn Corporation                 karl%grebyn.com@haven.umd.edu
P. O. Box 497                         {decuac,haven}!grebyn!karl
Vienna, VA 22183-0497                               703-281-2194

Re: Good Design Strategies <Was comments on comments>

[Bob Hathaway]

In article <2344@goofy.megatest.UUCP>, djones@megatest.UUCP (Dave Jones) writes:
>If you end up with "reusable and parameterized components ... loosely
>coupled... modular", then it doesn't matter how you got there.
>My argument is that in most cases, you are more likely to end up
>in such a software ecstacy if you use bottom-up design techniques,
>and you'll get there quicker.

We agree the components are desirable but a modular design should get you 
there quickly too.   By breaking the system into smaller pieces with each
piece providing some well defined and more manageable part of the system,
the components should emerge.  Not only for the objects, but for the software
tools as well.  

>I have tried to use the parts of other production compilers
>to do things other than pre-runtime compilation. Not as an academic
>exercise, but to produce real commercial products.  That's why I'm

Yes I have too.  I've taken a parser out of a 100,000 line compiler
and it wasn't pleasant.  I couldn't just take out the parser because
it was inextricable tied to the scanner and some semantics (typechecking)
was performed there too.  This undoubtable was due to efficiency reasons
and not top-down design.  If on the other hand the design had taken 
reusable software tools into account the parser, scanner, and type system
would be separate entities with each providing a well defined interface.
It would be infeasible to reuse or add another scanner and much effort went
into taking the pieces out to the point where they were reusable.  They
finally did provide reusable components, the parser (and type-system)
generated an idl file representing the parsed functions and was used
immediately by two applications.  Someone recently asked to use the
parser/type-system and since yyparse (the parser) was modified to return
an object representing all the parsed declarations before passing them
to idl routines for output, he had exactly what he wanted in no time.
With just a little foresight on the part of the compiler designers and
with a greater priority given to software reuse the front-end of the
compiler would have provided the "software ecstasy" sought.  Of course,
Adts would have added greater potential for reuse of the data structures
involved but the tools were important too.

>The argument for top-down design is based on some assumptions that are 
>seldom met.  If the project has these properties, top-down design
>can be the best order of business.
>
>   1. Design and implementation are distinct and separate activities.
>
>      If they are not, you can't do one from one direction, and the
>      other from the other direction.

For projects which are not large, I think design will correspond
to recognizing the objects and major software components of the system,
and probably informal coding.  This isn't a major effort and can force
recognizing all issues involved very early.  For large projects, design and
implementation should be separate.

>   2. A "correct design" can be identified without benefit of prototyping,
>      and it will inevitably be error free.

Aren't prototypes usually top-down and provide a skeletal framework to show
users so they can decide if the software is what they want, with each
function possibly stubbed out to provide simple or no service?   Or maybe
just a fast implementation to show the bottom level is even possible, but
I don't see what prototypability has to do with top-down design, to verify
the designs correctness?  I think prototyping can show the validity of a 
"correct design", in other words top-down design with the benefit of 
prototyping.

>Or maybe somebody thinks up an entirely different kind of top-end that 
>deals with the same kinds of objects.  Either way, you are likely SOL 
>because those low level routines knew too much for their own good.  Now 
>if the design at the low level is good, all is well.  Like I said, if you
>get there, it doesn't much matter how you got there. But which technique
>is less error-prone?

Good design will keep the low-level routines from knowing too much,
top-down or otherwise.  Just keep this in mind and you're SIL:-)

>I say, The bottom-up design provided them with software that didn't
>"know it was in a compiler".  Recall, I did not even know about that
>project when I started the compiler. 
>And I meant it literally when I said, "Try doing that with a Pascal
>compiler that was designed top-down to be a Pascal compiler."
>
>Actually try it.  
>

But with a modular design (top-down within modules) the tools are
functionally separate and they should not know they are a compiler, just
what their well defined function is to provide and an interface to meet.
I think keeping separate functionality separate is something thats really
important regardless of whether the encapsulation comes through packages,
processes, or whatever.  The same applies to objects, even when designed
top-down the lower level implementation of the Adt should be based on
components which are as generic as possible, I don't see how providing the
implementation calls for non-generic units since the recursive application
of good design will call for modular and generic components which are used
to implement the object.  I can see that if a designer throws away all
design principles after identifying the top level object he could end up
with an unstructured, data-structure oriented, special purpose implementation
but that should be easy to avoid.

Bob Hathaway
rjh@purdue.edu

Re: Good Design Strategies <Was comments on comments>

[Dave Jones]

From article <6126@medusa.cs.purdue.edu>, by rjh@cs.purdue.EDU (Bob Hathaway):

> 
> We agree the components are desirable but a modular design should get you 
> there quickly too. 
>

I'm not willing to give over the term "modular design" to the piecewise
refinement school. I design modules (or "classes", or "Atds", or
"components" or whatever).   Sometimes, but seldom, I actually do use
piecewise refinement as an design or implementation technique.
The modules are the "what". The piecewise refinement is the "how".
If you get good modules from piecewise refinement, good for you! I've
seldom seen anybody else pull it off, but that's no reason to presume
that it doesn't work for you.  My assertion -- must I repeat it again? --
is that good modules are more likely to come from a bottom-up approach.
Designing the top levels first is just too darn risky for my tastes.

> By breaking the system into smaller pieces with each
> piece providing some well defined and more manageable part of the system,
> the components should emerge.
>

Components might emerge. But how they emerge may be dictated by the
top level.  That's what I don't want.  The top level might have to change.
Why not just begin by designing components?  That way, they don't have
to "emerge".  They are part and parcel of the design itself.

> Not only for the objects, but for the software tools as well.

I've never seen it happen that way, but then I've only been doing this
stuff for eighteen years.  Maybe next week. :-)


...


I'm going to get out of the discussion for a while.  I've been spending
too much time on this as it is.  Let me just say one thing: I've known
some people -- and be assured that I do not intend to suggest that
Mr. Hathaway is in this camp -- who have preached piecewise refinement
as a dogma for so long that it would take something akin to a religious
conversion to get them even to consider other techniques.  I am trying
to point that it just that: a technique.  The product is the thing.
We are sometimes free to choose the best methods on a product-by-product
basis. Which method is best depends on the job at hand. Top-down design
and piecewise refinement is, in my opinion, seldom the best technique to
use.

Re: Good Design Strategies <Was comments on comments>

[Bob Hathaway]

In article <2542@goofy.megatest.UUCP>, djones@megatest.UUCP (Dave Jones) writes:
>...My assertion -- must I repeat it again? --
>is that good modules are more likely to come from a bottom-up approach.

Ok, I'll admit you've made a good point although I still think starting at
the top is the natural way to design systems (and algorithms).

>> By breaking the system into smaller pieces with each
>> piece providing some well defined and more manageable part of the system,
>> the components should emerge.
>>
>Components might emerge. But how they emerge may be dictated by the
>...

Ok, how about a quick example starting at top level.  When designing
a "Classical" compiler/interpreter front-end, I know the structure will
consist of a scanner to read input and a parser to read the grammar.  
I'll assume the parser functions return an intermediate code Adt for
triviality.  Now, I know I'll need a symbol table for identifiers and
reserved words and a token type to return to the parser, and we have:

|-------|       |------|     |------------|
|scanner|------>|parser|---->|intermediate|
|-------|       |------|     |    code    |
      \          /           |------------|
       \        /
        |-------|
        |symbol |
	|table  |
        |-------|

Their are four top-level modules immediately identified.  
1. Symbol Table 
    Provides a symbol_table_entry Adt (encapsulates a type).
    <Description>
    Operations
	a. lookup/insert
	   <Description>
	...
2. Scanner 
    Provides TokenType Adt (encapsulates a type).
    <Description>
    Operations
	a. Next_Token
	   <Description>
	b. Match_Token
	   <Description>
	...
3. Intermediate Code
    Provides Intermediate_Code Adt (encapsulates a type)
    <Description>
    Operations
	a. Make_Node
	   <Description>
	b. Make_Child
	   <Description>
	...
4. Parser
    Parses input (encapsulates functionally related subprograms).
    <Description>
    Operations
	a. Statement
		Returns an intermediate code representation of the 
		parsed statement...
	b. Parse
		Go for the whole thing:-)
	...

Thus, a modular design with Adts.  The design can proceed by identifying
the return values and parameters to operations and possibly some high level
pseudo code to insure the problem is well understood and all parts of the
system will work together as expected.  To begin the implementation we 
analyze the dependencies, almost always the Adts come last.
Dependencies
  parser:  	scanner, symbol table, intermediate code, 
  scanner: 	symbol table
  symbol table:	 nothing
  intermediate code: nothing
We can begin implementation with the intermediate code and symbol table
because we know what they need to provide and how they fit into the system
and because they don't depend on unwritten code.  Yes, the token, 
symbol table, and intermediate code Adts won't change much and
are good candidates for reuse; I wouldn't expect to add more than one
or two operations and change more than a few parameters for each Adt
above after the initial design is complete.  Each module provides a
well defined interface and encapsulates either a type (Adt) or a
set of functionally related subprograms (the parser).  After the top level
design is complete we can turn to the internal design of the Adts.
For example the intermediate code Adt may be complex requiring recursive
application of the above technique, i.e. top down.  So, a generic tree
Adt from a library can be used, and so on, nothing special purpose.
The parser functions can be designed top-down and implemented bottom-up,
so we'll know what gramatical constructs are necessary from the top and
get there fastest from the bottom (the preferred implementation technique
for parsers).  Efficiency considerations can come later *if* the system
doesn't meet its timing constraints, good design comes first.  We wouldn't
know where to optimize until profiling anyway.

Classification:
Object Oriented (design & implementation)
    Yes: objects identified, 2nd level design and coding begins with 
	 objects (data structures).
    No : no inheritance.
Top-Down (design)
    Yes: Top-down design is used within modules, especially in the parser.
    No : Structure charts were possible, but modules provided the best high
	 level view of the system.
Bottom-up (implementation)
    Yes: started with the lowest level Adt.  Generic linked lists, tree adts,
	 etc., would be used to implement the Adts from the bottom up.
What I call this mess:
    Modular design with abstract data types, top-down design within modules.
Reuse:
    All software tools and components are conceivably replaceable 
    and reusable.

>... Which method is best depends on the job at hand. ...

I agree, the above technique was chosen after carefully considering the 
problem and I have found it suitable for most, if not all applications.
Direct encoding of the design and implementation is possible in Ada
and to my understanding this is the preferred application of Ada's 
methodology.  Flamage and comments are welcome.  In view of the recent
object-oriented discussions, can anyone comment on how inheritance,
dynamic binding, or any other object oriented techniques fit into or
could improve the above scheme?  I'll be disappointed if the modular 
technique with Adts is the only one provided:-)

Bob Hathaway
rjh@purdue.edu

Re: Good Design Strategies <Was comments on comments>

[David P. Schneider]

Another point to note is that for large (complex) projects, identifying the
subject of ADTs (e.g., Object-oriented design) may require an analysis step
using traditional requirements-oriented techniques, such as  data-flow  di-
agrams.   The associated data dictionary would then be used to identify the
objects or components, and the transform bubbles would be used to  identify
the required operations on those objects.

Note that traditional software engineering (Pressman, for instance)  breaks
the pre-release part of a project into *three* phases: analysis first, then
design, and finally implementation.   Analysis  tries  to  identify  system
characteristics   and   requirements   without   going   into   design-  or
implementation-level descriptions (which would  prematurely  constrain  op-
tions); design translates the output of analysis into implementable specif-
ications, and implementation puts code behind them thar words.   Note  that
the differentiation is a matter of degree more than type.

I'm gearing up for a term paper on the subject  of  object-oriented  design
and software reuse in complex projects, and if you can provide me with some
additional references in the trade journals, or have  had  experience  with
using ADT/object-oriented design on large projects, your mail would be wel-
come.

                                                David P. Schneider
                                                     BiiN (tm)
                                                  Wednesday, 3.8

Re: Good Design Strategies <Was comments on comments>

[Stuart H. Ferguson]

+-- rjh@cs.purdue.EDU (Bob Hathaway) writes:
| In article <>, djones@megatest.UUCP (Dave Jones) writes:
| >...My assertion -- must I repeat it again? --
| >is that good modules are more likely to come from a bottom-up approach.
| Ok, I'll admit you've made a good point although I still think starting at
| the top is the natural way to design systems (and algorithms).
 [ ... ]
| Ok, how about a quick example starting at top level.  When designing
| a "Classical" compiler/interpreter front-end, I know the structure will
| consist of a scanner to read input and a parser to read the grammar.  
 [ ... ]

Bob goes on to develop a design for a compiler front end in a very
rational and structured top-down type way.

The problem with this example is that it already a solved problem.
Parsing computer languages is such a well solved problem in fact that
there are tools to generate these programs automatically from terse
formal descriptions.

The real test of a design methodology is to try it on a not-so-well
solved problem.  How would you go about designing a WYSIWYG text
processing program, or a hyper-text environment, or a graphical
user interface toolkit?  (If you've done these before, substitute
something you have no IDEA about how to design.)

The pure "top-down" approach starts with some black box called "the
system" which you then break into smaller units and those into even
smaller units until you have something you can implement in a page
or two of code.  The difficulty is that the first decision you have
to make (i.e. breaking "the system" into a first level of components)
is the most far-reaching and nearly impossible to make without knowing
the whole design first.

Also, you know that users are going to demand things you can't imagine
now, so how do you go about designing your systems now so they are
expandable enough to meet the needs of the future?

Reference:  David Parnas, Paul Clements "A Rational Design Process:
		How and Why to Fake It."  IEEE trans soft-eng Feb 1986

The first part of the article is priceless.
-- 
		Stuart Ferguson		(shf@well.UUCP)
		Action by HAVOC

Re: comments on comments

[William Thomas Wolfe,2847,]

From article <2325@goofy.megatest.UUCP>, by djones@megatest.UUCP (Dave Jones):
> In an article by rjh@cs.purdue.EDU, Bob Hathaway says that he usually
> uses ADT's to do top-down design and implementation. [...] But I don't 
> usually do top-down.  I do bottom-up.  Design, implementation, test, 
> everything.  [...] I'll freely admit, there are times when top-down 
> is the way to go.  But it's not the way I do most of the programs I 
> write by myself.  I start out with a "bottom" that consists of lots of
> [general-purpose] ADT's [...].  Next I use these to form ADT's which 
> are specific to the low-level objects under consideration, etc.  

    The relevant literature states, I believe, that most good programmers
    combine the top-down and bottom-up techniques; the programmer typically 
    starts with two interfaces and a semantic gap, and then builds each 
    interface in the direction of the other in some programmer-dependent 
    ordering, ultimately bridging the gap by joining the two interfaces at 
    some point in the "middle", somewhere between the two.

    Thus, rather than argue which face of the coin is better than the
    other one, perhaps the participants in this discussion should 
    recognize that each strategy has its advantages, and that each 
    functions best when applied in conjunction with the other. 


    Bill Wolfe, wtwolfe@hubcap.clemson.edu

comments on comments on reusability

[Rick Farris]

In article <6093@medusa.cs.purdue.edu> rjh@cs.purdue.EDU (Bob Hathaway) writes:

> (I write)
> >|This seems to go backwards.  Programmers should first design
> >|their software then implement it.  You seem to be advocating 
> >|implementation then design.  The descriptive algorithm should 
> >|come first, then the code.

> In article <9689@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes:
> >I have a problem with Top-Down programming (design then
> >implementation); it happens to be the same problem I have with
> >Bottom-Up programming (implementation then design).  You so eloquently
> >point it out in your next sentence:  

Something that neither one of you guys addressed, and that I think is
crucial to the whole "Top-Down Design" issue, is reusability.
Top-down design implies leaves that are custom made for the program
at hand.  Reusability implies molding the problem definition around
leaf (and maybe not-so-leaf) modules that are already available.
After all, for a hardware design, you wouldn't design your own ICs,
would you?

One of Ada's major strengths is it's facilities to design for re-use,
and we designers have to come to grips with the idea that we're not
going to be doing "optimal" designs anymore.

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


Rick Farris   RF Engineering  POB M  Del Mar, CA  92014   voice (619) 259-6793
rfarris@serene.cts.com     ...!uunet!serene!rfarris       serene.UUCP 259-7757

Re: comments on comments on comments

[William Thomas Wolfe,2847,]

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

Re: comments on comments on comments

[William A. Bralick]

In article <4534@hubcap.UUCP> wtwolfe@hubcap.clemson.edu writes:
:-)
:-)  [lots of stuff lost in space (uh, time (uh, space (uh, you know)))]
:-)
:-)  Also, I've learned to type very quickly, through long hard experience.  :=)
:-)

I personally like to abstract data type.  I belly-up to the ol' keyboard
abstraction and type my data: long or short, integer or real (oops, I
can't type real data on my abstract keyboard (it can only handle concepts 
on the order of aleph-null (due to strong typing))).

Regards (from the Time Coast),


-- 
Will Bralick : wbralick@afit-ab.arpa  |  If we desire to defeat the enemy,
Air Force Institute of Technology,    |  we must proportion our efforts to 
                                      |  his powers of resistance.
with disclaimer;  use disclaimer;     |               - Carl von Clauswitz

Re: comments on comments on comments

[Rick Farris]

In article <4534@hubcap.UUCP> wtwolfe@hubcap.clemson.edu writes:

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

[some examples deleted]

Yes, this is the only way I've seen documentation that tended to be
maintained with the code.  Personally, I'm a proponent of 4th
generation reverse engineering tools to do things like structure
charts, etc, since they are *never* maintained if it has to be done
manually. 


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


As the ADAge goes, "Programs are *written* once, but *read* many times."


Rick Farris   RF Engineering  POB M  Del Mar, CA  92014   voice (619) 259-6793
rfarris@serene.cts.com     ...!uunet!serene!rfarris       serene.UUCP 259-7757

Re: comments on comments on comments

[Robert Claeson]

In article <4534@hubcap.UUCP>, billwolf@hubcap.clemson.edu (William Thomas Wolfe,2847,) writes:

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

I used to do that until I heard that the ANSI C standard will state
that external identifiers should not be equal in the first six
characters. Maybe POSIX says something else. I don't plan to port
my code to anything else than POSIX (and maybe PC-DOS, if I have to).

I also label each identifier with two to four characters that indentifies
a package. For example, the functions in my package for handling double-
linked lists in C has functions like "dlst_create_list" and
"dlst_next_item".
-- 
Robert Claeson, ERBE DATA AB, P.O. Box 77, S-175 22 Jarfalla, Sweden
Tel: +46 (0)758-202 50  Fax: +46 (0)758-197 20
EUnet:   rclaeson@ERBE.SE               uucp:   {uunet,enea}!erbe.se!rclaeson
ARPAnet: rclaeson%ERBE.SE@uunet.UU.NET  BITNET: rclaeson@ERBE.SE

Re: comments on comments on comments

[Rick Clements]

In article <2989@uvacs.cs.Virginia.EDU> you write:
>In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:
>>What is needed to improve self-documentation are better programming languages.

>This is certainly true, but even the "better" programming languages allow for
>the inclusion of comments. There will probably always be parts of the 
>programmer's concept which need to be expressed in an informal way through
>comments.

I have learned to include comments like "Doing it <this_way> appeared obvious
at first but didn't work because of <something>".  I hate solving the same
problem twice (even if it a year or so later).  You can also list what trade
offs lead you to solve a problem the way you did.  The code can never tell
you the why.  Telling the person maintaining the code (maybe yourself) why
something was done will help them from creating those crash every 5th
Tuesday type of bugs.
----
Rick Clements (RickC@pogo.WV.TEK.COM)

-- 
Rick Clements (RickC@pogo.WV.TEK.COM)