Re: comments on comments

[rjh@cs.purdue.EDU (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