comments on comments 
Author Message
 comments on comments

(I write)

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

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

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

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

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

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

Be conscientious!

Bob Hathaway



Mon, 20 Jul 1992 02:15:00 GMT  
 comments on comments

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.



Mon, 20 Jul 1992 07:22:00 GMT  
 comments on comments

Quote:

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

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

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



Mon, 20 Jul 1992 20:41:00 GMT  
 comments on comments

Quote:


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

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

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

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

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



Mon, 20 Jul 1992 22:50:00 GMT  
 comments on comments

Quote:

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




Mon, 20 Jul 1992 01:57:00 GMT  
 comments on comments

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




Mon, 20 Jul 1992 02:15:00 GMT  
 comments on comments
:-)
:-)  [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),

--

Air Force Institute of Technology,    |  we must proportion our efforts to
                                      |  his powers of resistance.
with disclaimer;  use disclaimer;     |               - Carl von Clauswitz



Mon, 20 Jul 1992 03:31:00 GMT  
 comments on comments

| 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



Mon, 20 Jul 1992 09:24:00 GMT  
 comments on comments

Quote:

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



Mon, 20 Jul 1992 01:07:00 GMT  
 
 [ 53 post ]  Go to page: [1] [2] [3] [4]

 Relevant Pages 

1. comments on comments

2. meta-comments for comments on proposals

3. comments on comments

4. Counting commented lines (full-line comments only)

5. Single Pound # comments versus Double Pound ## comments

6. How does your language grow? (Follow-up on comments on ADM Tuttle comments)

7. convert ! comments to standard comments?

8. Class comments

9. smalltalk parser and comments

10. - Your comments wanted!

11. Comment on APL and parallel hardware

12. apl2ital for TeX additional comments

 

 
Powered by phpBB® Forum Software