[comp.software-eng] comments on comments

djones@megatest.UUCP (Dave Jones) (02/10/89)

There was some discussion about comments recently in comp.lang.c.

(Notice the followup-to line. Seems like the most appropriate
 group. Hope you agree. I'm not too familiar with the group,
 having just recently subscribed.)

I'm not a religious fanatic about it, but in maintaining lots of
different code since 1979, I have developed some preferences for what
I like in the code I am charged with maintaining, and what I could
do without.

Here are some remarks that I wrote up for one of the
members of my programming team.  I hope they will be
helpful.

....

In my opinion, the most important parts of a program to document
are the structure-declarations and the variable-declarations.
You document what the fields and variables "mean" in terms of
invariants.  Use descriptive names in addition to comments,
and don't use non-conventional abbreviations. If you do that, and
if the code is well structured, documenting an algorithm is usually
(but not always) unnecessary. Usually it is obvious how the algorithm
will go about the process of reestablishing a broken invariant.

Except in unusually tricky cases, the documentation for
a procedure should only say WHAT the procedure does, not
HOW it does it.  If the algorithm is not tricky, the WHAT
will make the HOW clear enough.   Comments which assert
the obvious are just clutter, worse than nothing.

Before you put comments into a procedure, ask yourself whether
there is some way to make the procedure itself understandable,
on its own. Perhaps you can give some variables more descriptive
names. Or you might even change the control flow. You may be
happily surprised to find that the clearer algorithm is actually
better!

A good way to sum this up would be to say, document things
which would be difficult or impossible for the maintainer
to surmise. If something is easy to figure out, don't
bother the reader with a comment. If something is hard to
figure out, ask yourself whether the complexity is necessary.

A comment which is inaccurate is worse than no comment.
Thus, comments should be "robust".  They should either
say things that are likely to remain true over the
lifetime of the code, or they should be positioned so
that it will be obvious to the maintainer when he
invalidates a comment.

For this reason, comments should only refer to their immediate
surroundings. If a comment says, "The previous four routines do
so and so...," a code-maintainer is likely to move one of the 
routines, or alter one without even knowing that he is "breaking" 
a comment. The same is true if a comment says, "This routine is
called by procA, and procB."  The maintainer of procA or
procB may not even know about the comment.  There are
utility programs for generating such cross-reference
information directly from the sources, without trusting
in comments.

Documentation about more general relationships between procedures
belongs in a separate design document, or in interface (#include)
files. Remember, it is the data-invariants which give
purpose to the procedures. Describe the data-invariants where
the data structures and variables are declared, typically
in #include-files.

If you want to make comments to yourself while you are
developing or maintaining the code, that's fine.  Things like,
"When this is integrated, routine foo() will call this routine...",
or "I think this probably does so and so."

But comments such as these should be marked somehow so
that they will be easy to remove later. I have found such
comments in code fourteen years old!   You don't want
to leave them there, so make it easy to remove them later.
I usually tag them with my login-name, which I certainly
DON'T want to leave in the code!

Block comments which are neatly delimited on the right margin
may look pretty, but they are hard to modify:

/************************/
/* This looks tidy, but */
/* it is hard to main-  */
/* tain.                */
/************************/

There's another problem with the comment above: It's not
one comment; it's several.  Utilities which look for comments
with certain keywords, etc. will not treat the above as one
comment.

Here's a good way to go about it:

/*******************************
 * This is one block comment,
 * and it is easy to modify.
 ******************************/

rjh@cs.purdue.EDU (Bob Hathaway) (02/11/89)

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

hughes@math.Berkeley.EDU (eric hughes) (02/11/89)

In article <1813@goofy.megatest.UUCP>, djones@megatest (Dave Jones) writes:
>In my opinion, the most important parts of a program to document
>are the structure-declarations and the variable-declarations.
>You document what the fields and variables "mean" in terms of
>invariants.

To add to this, I will often explicitly make a comment that a
certain variable is "valid," that is, it satisfies all the
invariants of its type, as well as ones specific to the variable.
Then I am very careful not to use a variable which is not shown
to be valid.  If part of it is, I'll declare that part valid and
use it.  This technique has prevented many stupid bugs.

>					       If you do that, and
>if the code is well structured, documenting an algorithm is usually
>(but not always) unnecessary. Usually it is obvious how the algorithm
>will go about the process of reestablishing a broken invariant.

I always document an algorithm, not matter how silly.  This has
helped me avoid what I term "typo bugs," things I meant to do
but forgot.

>		  If the algorithm is not tricky, the WHAT
>will make the HOW clear enough.   

Yes, a good statement of the preconditions and postconditions to a
function can eliminate most procedural comments. (e.g. now we need to
do this, now that.)  Rather than use a procedural comment before I do
something, I will use an assertion comment about the program state
afterwards.  This is more useful to me, since it is more detailed and
states exactly what just happened, not what I intended it to do.  For
some reason, I find it easier to objectively look at an assertion than
an intention.

>				   Comments which assert
>the obvious are just clutter, worse than nothing.

I have found that my grasp on the obvious is not what I
think it is. :-)  My rule of thumb is not to comment anything
which is implicit in the syntax of a statement, but I will 
sometimes comment on the semantics (especially in the case of
function calls) and always on the pragmatics (what effect it
has).

I had a friend once who was taking an assembly language class
where the teacher required every program line to be commented.
He wrote a filter to translate every instruction into it English
equivalent and present it as a comment on that line.

	LOAD AX, 1		; load the register AX with the value 1

The teacher was satisfied and the student got good scores
on his programs.  This is the kind of syntax-based comment I
avoid.

In a related issue, I have found that program correctness techniques
are a good way of documenting code.  Not only to they allow you to
know that what you are doing is correct, but, more importantly, they
are the most concise way of stating exactly what the program does.
It is elegant to my mind because it is as simple as possible, but
no simpler.

Every loop gets both a loop invariant and a bound function in a 
header before it starts.  At the end, the termination conditions
are stated explicitly.  From that, I separately assert the desired
postcondition for the loop.  I have found this accurately describes
both what the loop does and the outline of how it works.

Now I would like some engineering tools with which I could check my
correctness proofs, but since none exist (to my knowledge), I have
found that conscientious commenting is acceptable.

Eric Hughes
hughes@math.berkeley.edu   ucbvax!math!hughes

perry@apollo.COM (Jim Perry) (02/14/89)

In article <20233@agate.BERKELEY.EDU> hughes@math.Berkeley.EDU (eric hughes) writes:
>In article <1813@goofy.megatest.UUCP>, djones@megatest (Dave Jones) writes:
>
>>				   Comments which assert
>>the obvious are just clutter, worse than nothing.
>
>I have found that my grasp on the obvious is not what I
>think it is. :-)  My rule of thumb is not to comment anything
>which is implicit in the syntax of a statement, but I will 
>sometimes comment on the semantics (especially in the case of
>function calls) and always on the pragmatics (what effect it
>has).
>
>I had a friend once who was taking an assembly language class
>where the teacher required every program line to be commented.
>He wrote a filter to translate every instruction into it English
>equivalent and present it as a comment on that line.
>
>	LOAD AX, 1		; load the register AX with the value 1
>
>The teacher was satisfied and the student got good scores
>on his programs.  This is the kind of syntax-based comment I
>avoid.
>

Let me begin by saying that I'm in the camp calling for more comments.
Especially in the Unix/C world, the overwhelmingly vast majority of
programs are undercommented.  It's interesting that some aspects of
programming style, e.g. indentation, are fairly consistently applied,
while adequate documentation is the remote exception.

In your example, the chances are that there is some meaningful piece of
information that could have been conveyed -- "start with the first 
widget" -- rather than restating the language-level semantics.  [Did
you ever see this friend's filter?  I suspect this is an urban myth, as
rumors of such "tools" was common (at Dartmouth, and I'm guessing elsewhere)
in the mid-to-late '70's.]

Consider writing such a filter for C programs.  C crams so much stuff into 
a small area that just expressing what's going on, in English, would
generate huge comments.  I consider this very fact an argument for the
programmer taking the time to construct a pithy description of what a piece
of code is intended to do.  And I do, by and large, comment every line.

Code should be self-documenting, at all levels.  The main body of a program
should explain what the program does, what the dependencies, files, etc.
are, and so on.  The data declarations should explain what the data
structures are and how they are used.  Functions, modules, procedures,
macros, etc. should also explain themselves, and so on.  This is part of
what differentiates engineering from hacking.  (The comment-generating
program might be the ultimate in hackery, in this context).

I would have to say that with the possible exception of some overzealous
undergraduate student projects, I've never seen an overdocumented program,
and I've seen a vast, vast number of underdocumented ones.  I've seen some
poorly though verbosely documented ones, as discussed here and elsewhere
not all programmers have great communication skills, but never has this
been "worse than nothing".  
-- 
Jim Perry   perry@apollo.com    Apollo Computer, Chelmsford MA
This particularly rapid unintelligible patter isn't generally heard
and if it is it doesn't matter.

dhesi@bsu-cs.UUCP (Rahul Dhesi) (02/14/89)

>>He wrote a filter to translate every [assembly] instruction into English
...
>>	LOAD AX, 1		; load the register AX with the value 1
>>This is the kind of syntax-based comment I
>>avoid.

I come across samples of assembly code for many different machines in
books, journals, magazines, source listings, etc., and it is not always
easy for me to understand them.  If each instruction were accompanied
by an English comment, life would be much simpler for all of us.
-- 
Rahul Dhesi         UUCP:  <backbones>!{iuvax,pur-ee}!bsu-cs!dhesi
                    ARPA:  bsu-cs!dhesi@iuvax.cs.indiana.edu

hughes@math.Berkeley.EDU (eric hughes) (02/14/89)

In article <20233@agate.BERKELEY.EDU> I write:
>>I had a friend once who was taking an assembly language class
>>where the teacher required every program line to be commented.
[story deleted]

In article <4173bd76.183dc@apollo.COM>, perry@apollo (Jim Perry) writes:
>[Did you ever see this friend's filter?  I suspect this is an urban
>myth, as rumors of such "tools" was common (at Dartmouth, and I'm
>guessing elsewhere) in the mid-to-late '70's.]

I am almost sure it is not.  I have a particular friend in mind,
who know works in Boston.  As I recall, he wrote it for an IBM-PC
for MASM code and the filter was implemented in SNOBOL, a string
processing language.  I may be mistaken.  I will call him up
and find out for sure.

Eric Hughes
hughes@math.berkeley.edu   ucbvax!math!hughes

nevin1@ihlpb.ATT.COM (Liber) (02/16/89)

In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes:

>Let me begin by saying that I'm in the camp calling for more comments.

I'm not.  I do agree with you on the problem (poor documentation), but
I do not think that more comments is the answer.

>Especially in the Unix/C world, the overwhelmingly vast majority of
>programs are undercommented.  It's interesting that some aspects of
>programming style, e.g. indentation, are fairly consistently applied,
>while adequate documentation is the remote exception.

The question is:  Why?  From my point of view, good documentation in
the form of comments is rare because there is NO WAY of guaranteeing
that they are correct with respect to the code.  They are a nightmare
to maintain, and no one ever has the time to fix the comments when the
code has fatal bugs.  Also, no one wants to take the time to rewrite
their code into English; it's a boring, tedious job, and when it comes
down to it only the code really matters to those buying your software.
It is human nature to take the path of least resistance; comments go
against this path.  With very few exceptions, for better or for worse,
this is the way of the world.

Will requiring Joe Programmer to write more comments fix the situation?
No.  Joe Programmer will find a way to keep his comment writing to a
minimum, even if the code or organization of modules has to suffer for
it.

>C crams so much stuff into 
>a small area that just expressing what's going on, in English, would
>generate huge comments.  I consider this very fact an argument for the
>programmer taking the time to construct a pithy description of what a piece
>of code is intended to do.  And I do, by and large, comment every line.

Suppose you require Joe Programmer to comment every line of his C code.
What does Joe Programmer do?  He writes:

	(void)strcpy(string0, string1);
	(void)strcat(string2, string3);
	(void)strcat(string0, string2);
as

	(void)strcat(strcpy(string1, string0), strcat(string2, string3));

because he only has to comment one line instead of three.  The code is
less readable in case 2, but Joe Programmer has achieved your goal (a
comment on every line) with less effort.  (Note:  the opposite problem
is true when you are measuring number of lines of code as a quality
measure:  Joe Programmer might rewrite line one of the first case as

	(
	void
	)
	strcpy
	(
	string0
	,
	string1
	)
	;

and make a tenfold improvement in his statistics!)

Here are some real-world examples of what happens when you force a
programmer to write lots of comments:

Requirement:	require file comments in each source file.
What Happens:	Many functions are stuffed into a single source
		file, irregardless of whether the functions are related
		or not.

Requirement:	require block comments for each function declaration.
What Happens:	Functions become less modular.  In C, a programmer might
		stuff five functions into one by using a giant case
		statement.

Requirement:	always provide a list of what a given function calls
		and is called by.
What Happens:	These comments are out of sync very fast.  This kind of
		documentation is much better handled by a
		software tool than by a programmer.

Unfortunately, I have seen the What Happens all too often.
Forcing programmers to write more comments is not the answer.  What
is?

>Code should be self-documenting, at all levels.  The main body of a program
>should explain what the program does, what the dependencies, files, etc.
>are, and so on.  The data declarations should explain what the data
>structures are and how they are used.  Functions, modules, procedures,
>macros, etc. should also explain themselves, and so on.

This is the solution:  code should be self-documenting.  But,
self-documenting is not the same as commenting!  When I change a line
of code, my documentation should reflect that change automagically.  I
don't get this with comments, and because of it, the only comments I
rely on are my own personal ones.

What is needed to improve self-documentation are better programming
languages.  This is one of the reasons that, for example, C++ is better
than C; the resulting code is more self-documenting.  The language has
to make it easier for me to abstract and be more self-documenting than
not; this is the key to solving the problem.  The ultimate programming
language(tm :-)) will be one where I will never have to write a single
comment; it should be clear, concise, and obvious from the code my
intentions of what I was programming.  We need to improve our
programming languages, not increase the quantity of our commenting.

>I've seen some
>poorly though verbosely documented ones, as discussed here and elsewhere
>not all programmers have great communication skills, but never has this
>been "worse than nothing".  

There are many instances on where poorly documented code is "worse than
nothing"; most notably, when the comments are WRONG!  It has happened
too many times that someone reads the comments on how the routine is
"supposed to" work, makes a change, and finds out that the
implementation is totally different than the comments.  I wonder how
many lost man-years in software maintenance can be attributed to this.
-- 
 _ __	NEVIN ":-)" LIBER  nevin1@ihlpb.ATT.COM  (312) 979-4751  IH 4F-410
' )  )			 "I will not be pushed, filed, stamped, indexed,
 /  / _ , __o  ____	  briefed, debriefed or numbered!  My life is my own!"
/  (_</_\/ <__/ / <_	As far as I know, these are NOT the opinions of AT&T.

garison@mirror.UUCP (Gary Piatt) (02/16/89)

>Forcing programmers to write more comments is not the answer.  What
>is?

The solution is to give these programmers their own code after four
or five years, and have them modify it (Note: MODIFY, not RECREATE).
In one of my former lives (in 1984), I was called upon to change the
terminal emulation software I had written to allow it to access multiple
display pages.  I had done this four years prior to that day, and
decided to save myself a day's work by resurrecting the older code
and modifying it to fit the new environment.  Well, it didn't work 
that way.  The comments on the old code were what you would refer to
as "sparse" ("This loads the new page" at the head of twenty lines of
code).  Instead of saving time, I ended up wasting time; it took me
the entire day to understand what I had written only four years before.
No matter how good a programmer you are, or how long you've been in
the business, you can't expect yourself to remember the intent of every
line of code you've ever written.

These days, I comment (almost) every line, and WHEN I CHANGE THE CODE,
I CHANGE THE COMMENT.  When I'm done with the program, and I know that
it works, I take the time to add headers to each function, describing
what it does and how it works.  This method has paid off.  Last year 
the company I worked for in 1984 called me back as a consultant to fix
an obscure little bug they had discovered in the software I had written
that year.  I quoted them a price (and they paid me) for the entire day,
but -- because of those comment -- the job only took two hours.

			-garison-


...good comments are like good sex:  too much is never enough

EGNILGES@pucc.Princeton.EDU (Ed Nilges) (02/17/89)

In article <9606@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes:

>I'm not.  I do agree with you on the problem (poor documentation), but
>I do not think that more comments is the answer.

     The answer is not "more comments", you're right.  The answer is
     "more programs with better written, more accurate comments; and
     maintenance programmers with more time to update the code as well
     as the comments."

>
>The question is:  Why?  From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare
>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.
>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.

     There is also NO WAY of ensuring that the code itself is correct,
     period.  Does this mean we should not write code?  Of course not.
     In my 17-odd years of experience, much of it spent maintaining
     other people's code, I have never been misled by a comment.  I
     have, on the other hand, wasted time where a comment would have
     shown me the way.

     In "no one wants to take the time" you are referring to people
     who like to code before they decide, and WRITE DOWN, what their
     code shall do.  It's my humble opinion that these people shouldn't
     code.  Previous posters to this thread have emphasized that the
     best comments are written prior to code and state the purpose of
     what shall be coded.
>
>Will requiring Joe Programmer to write more comments fix the situation?
>No.  Joe Programmer will find a way to keep his comment writing to a
>minimum, even if the code or organization of modules has to suffer for
>it.

     I'd hate to work for someone with such a low opinion of programmers.
>
>
>Suppose you require Joe Programmer to comment every line of his C code.

     Nobody requires programmers to comment C code.  The "every line
     commented" is a standard for assembly language.  C programs require
     instead function purpose statements, placed at the beginning of
     each function.

>
>Here are some real-world examples of what happens when you force a
>programmer to write lots of comments:
>
     These examples describe the behavior of people who should not be
     trusted to program computers.  I do agree that software tools
     can be used to help keep code and documentation up to date; for
     example, I am currently developing a lot of EXECs for VM/CMS,
     and I write the initial "METAEXEC" using Script, both to format
     the descriptive comments and as a macroprocessor for executable
     code.  Since the text formatting commands have access to the
     same SET symbols as does the EXEC code, I can change the value
     of a SET symbol and have the code and comment change at the same
     time:

          .se maxwords = 1500
          .
          .
          .
          /* This software can process at most &maxwords words...
          .
          .
          .
          IF inwords > &maxwords then SAY "Too many words"

     However, it is the maintenance programmer's job to update docu-
     mentation as well as code.
>
>What is needed to improve self-documentation are better programming
>languages.  This is one of the reasons that, for example, C++ is better
>than C; the resulting code is more self-documenting.  The language has
>to make it easier for me to abstract and be more self-documenting than
>not; this is the key to solving the problem.  The ultimate programming
>language(tm :-)) will be one where I will never have to write a single
>comment; it should be clear, concise, and obvious from the code my
>intentions of what I was programming.  We need to improve our
>programming languages, not increase the quantity of our commenting.

     But the best comments are statements of purpose, and the
     Ultimate Programming Language shall not decide for us what
     use shall be made of it!  Also, remember us mortals, who must
     sputter along in FORTRAN and C...

Edward Nilges

"Where is the wisdom we lost in knowledge?  Where is the knowledge we
 lost in information?" - T. S. Eliot

peter@ficc.uu.net (Peter da Silva) (02/17/89)

In article <9606@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes:
> The ultimate programming
> language(tm :-)) will be one where I will never have to write a single
> comment; it should be clear, concise, and obvious from the code my
> intentions of what I was programming.  We need to improve our
> programming languages, not increase the quantity of our commenting.

I think this is an unreachable goal.

If this was possible, we'd not have any lawyers. Everyone would know
the intent of any document, law, etc.... It would be obvious from the
Constitution whether personal assault rifles are a good idea (and if you
think they are, consider personal nerve gas or personal nukes).
-- 
Peter da Silva, Xenix Support, Ferranti International Controls Corporation.
Work: uunet.uu.net!ficc!peter, peter@ficc.uu.net, +1 713 274 5180.   `-_-'
Home: bigtex!texbell!sugar!peter, peter@sugar.uu.net.                 'U`
People have opinions. Companies have policy. And typos are my own business.

lewis@sigsun.cad.mcc.com (Dave Lewis) (02/17/89)

Here's my comments on your comments about comments!

>In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes:
>
>>Especially in the Unix/C world, the overwhelmingly vast majority of
>>programs are undercommented.  It's interesting that some aspects of
>>programming style, e.g. indentation, are fairly consistently applied,
>>while adequate documentation is the remote exception.

WHY is indentation almost universally used?  Because the payback to the
programmer is immediate and effective!

Why is adequate documentation a remote exception?  I don't think that
it's a question of correctness, although this is a demotivating factor.
Rather, I think that the typical comment does not convey any useful
information to the programmer later.  Indentation does, so it gets done.
>
>The question is:  Why?  From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare

It's all relative; there is no way to guarantee that the program won't
throw up on you the very next time you run it!  If there is no possible
way to verify correctness of the comments, then the code is not understandable,
can not be modified, and must be retired as soon as anything serious 
happens to it.  This is an extreem view, and of course in practice
it's very tedious to verify comments...

>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  
Most comments that I have seen don't document the fact that a program
has a fatal bug.  In fact, usually they state what should be happening,
but the reality is that something happened that the code was not designed
for.  Most times, simply stating what the problem was, and the reasoning
behind the method of the fix is the appropriate action.

>Also, no one wants to take the time to rewrite
>their code into English; 

I agree, this is useless - the code already states what it's doing!
AND I think that this is a perfect example of why comments are not
useful to programmers - as written they don't add any information
to the program.  It's only when you come back the next year that you
have the proper perspective on what comments should have been there!

>it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.
>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.

...the path of least resistance...   Agreed.  The trick is that the
comments should greatly lower the resistance the next time you look
at the code.  Certaintly, indentation does!

lots of stuff about programmers getting around various requirements deleted.

>There are many instances on where poorly documented code is "worse than
>nothing"; most notably, when the comments are WRONG!  It has happened
>too many times that someone reads the comments on how the routine is
>"supposed to" work, makes a change, and finds out that the
>implementation is totally different than the comments.  I wonder how
>many lost man-years in software maintenance can be attributed to this.

Not too much... most maintainers will verify comments if they can.  What's
the alternative?  The alternative is to spend an enormous amount of time
analzying what the code is doing, and knowing that, theorizing about why
it's doing it that way, and what the trade-offs were when the data structures
were designed, whether it was done that way for efficiency, or was it just
the easiest way to do it?  This alternative is what consumes the most time
in software maintenance.  The NECESSITY to do this is virtually what 
DEFINES the nature of the work as maintenance!   If you didn't need to do
this, it is either a very rare program, trivial, or you are still in the 
initial development phase.

Sorry this was so long...


Dave Lewis @ MCC CAD Program [512] 338-3663 | ARPA: lewis@mcc.com
UUCP: {uunet,harvard,gatech,pyramid}!cs.utexas.edu!milano!cadillac!lewis

vfm6066@dsacg3.UUCP (John A. Ebersold) (02/17/89)

My observations.

IMHO comments should document:

Why a particular data structure is being used. 

Why that *seemingly* silly bit of code was written.  You know, the code your
read and a say to yourself.  "This is stupid.  It doesn't need to be done
this way.  I'll change it."  GOTCHA.

Comments should documents side effect created or depended on - I know,
a bad idea but it happens.

Module comments should give the big picture.

Comments should NOT restate the syntax.

Programmer who write comments like:

/*
** See if you can figure this out.  Ha.
*/

should be condemmed to writing an operating system in BASIC without using
GOSUB.

We see the frenzied Maintainence Programmer grabbing shirt of
the perpetrator of the above comment and hear the sound of their hand
knocking sense into the errant comment writer.  Smeck, smeck, smeck,
smeck, smeck.

The right way to write a comment :-) :

I once wrote a twenty line comment to document on interrupt handler, its
expected data arrival rate, how it could be blown out of the water and why
it probably would not happen.

The interrupt handler was less than ten lines of C code.

-- 
Speaking for myself:
John A. Ebersold, Unify Corporation @ Defense System Automation Center
osu-cis!dsacg1!dsacg3!vfm6066	      Columbus, Ohio 1-614-238-5923 AV-850 5923
Systems with poorly understood requirements cannot be developed in a crunch.

rjh@cs.purdue.EDU (Bob Hathaway) (02/18/89)

>                      Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes

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

>Will requiring Joe Programmer to write more comments fix the situation?
>No.  Joe Programmer will find a way to keep his comment writing to a
>minimum, even if the code or organization of modules has to suffer for
>it.

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

>This is the solution:  code should be self-documenting.  But,
>self-documenting is not the same as commenting!  When I change a line
>of code, my documentation should reflect that change automagically.  I
>don't get this with comments, and because of it, the only comments I
>rely on are my own personal ones.

I've always believed in self-documenting code and used this excuse
to avoid commenting until I graded a systems programming course
about a year ago.  The programs which had long procedures, few comments,
and weren't self documenting (*to me* at least) were the worst.  Trying to
work with these programs in a professional environment would have been a
nightmare.  The self-documented programs which kept their procedures
small and abstracted a single function were by far the best but
comments were still necessary.  Uncommented programs take several times
longer to read and understand than commented ones.  After my experience 
grading and after working with several large programs my conclusion is that
well commented, self-documenting code is by far the best.  Also, forcing 
an a-priori design and including this design in comments will not only
produce higher quality and better designed programs but programs which are
more easily understood since the structure of the software is documented.

>intentions of what I was programming.  We need to improve our
>programming languages, not increase the quantity of our commenting.

I agree entirely and advocate languages which allow direct expression of
algorithms and design.  But since current languages are approaching that
point and are not yet there, commenting is still necessary.

>There are many instances on where poorly documented code is "worse than
>nothing"; most notably, when the comments are WRONG!  It has happened
>too many times that someone reads the comments on how the routine is
>"supposed to" work, makes a change, and finds out that the
>implementation is totally different than the comments.  I wonder how
>many lost man-years in software maintenance can be attributed to this.

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.

Bob Hathaway
rjh@purdue.edu

shf@well.UUCP (Stuart H. Ferguson) (02/20/89)

+--- From: nevin1@ihlpb.ATT.COM (Liber)
| I do agree with you on the problem (poor documentation), but
| I do not think that more comments is the answer.

Perhaps it's quality that matters, not quantity.

| [...] only the code really matters to those buying your software.

That may have been true in "the old days," but people expect a lot more
than mere functionality from modern software.  People are buying not 
just the program, but "support," which means documentation, bug fixes
and updates.  All of this is easier with well commented code.

| It is human nature to take the path of least resistance; comments go
| against this path.

I used to think this too.  I started, in "the old days," writing machine 
code directly into core memory.  There was no such thing as source.  
Comments were a list of addresses and what they contained kept in a pile
of ragged sheets of loose yellow paper.  A "patch" was a jump to a free 
section of memory to execute new code which then jumped back.  The heart 
of the matter -- what the customer paid for -- was the raw code, the 
stream of machine instructions that WERE the program.  The "comments" were 
auxiliary, for my use only.

(We still have a piece code like that, and the only person who can do
anything useful with it is the original programmer.  I fear he may be
wedded to that program for the rest of his life...)

As time passed and I matured as a programmer, however, my opinion of the
role of "code" and "comments" reversed.  I think I would now be happier
with a language that was all comments, with tokens to delimit code,
rather than the other way around.

Code is only understandable in a context.  For the 'C' language, for
example, K & R, or some other 'C' reference work, provides the 
background for understanding a usage of the notation.  The fragment,

	for (i=0; i<N; i++)

means nothing outside the context provided by the "commenting" of the
language semantics.  Likewise, the comments for a particular program
can establish the role of such a construct within the overall context
of the design.

It's a little like mathematics.  Despite how advanced and really
sophisticated mathematical notation has become over the centuries, all
math textbooks consist of some limited number formal statements of
theorems as required, surrounded by a lot of discussion which places
the theorems in a context with the rest of math.  The discussion --
the "comments" -- are at least as much of the math as the formal 
expressions.  There wouldn't be math without the formalisms, but there
also wouldn't be math without the stated context.  Both are essential.  

| This is the solution:  code should be self-documenting.  But,
| self-documenting is not the same as commenting! [...]
| What is needed to improve self-documentation are better programming
| languages.  This is one of the reasons that, for example, C++ is better
| than C; the resulting code is more self-documenting.  The language has
| to make it easier for me to abstract and be more self-documenting than
| not; this is the key to solving the problem.

Again, no programming language is "self documenting."  For a formal 
domains like 'C' or 'C++', the context is provided by the reference 
works on the language which set forth the "philosophy" of the domain
as well as the formalisms.  Without that context, the code is just so 
much jibberish.

When we write programs, we are creating a new domain consisting of 
new objects (data structures) and new operations (functions or
subroutines).  Like other formal constructs such as programming
languages and mathematical derivations, the meaning cannot be implied
without some background.  We need to provide the context, to 
describe the underlying design, which allows other people to navigate 
in the worlds we create.

| The ultimate programming language(tm :-)) will be one where I will
| never have to write a single comment; it should be clear, concise, 
| and obvious from the code my intentions of what I was programming.

I think "comments" are not something separate from the code but are
rather an integral aspect of any design.  My UPL (since we're 
engaging in fantasy :-) would be a combination of conventional 
programing and hypertext -- a kind of Hyper-Programming (tm).  The
program itself would appear as a mixture of graphs, block diagrams,
pseudocode and straight prose.  I might create a graphical icon for a 
data structure that would appear in the flow diagram for an algorithm, 
and I could expand this icon to show its formal description with some
prose describing its purpose and a display showing how the data
structure can be used.  Part of this display might be generated by the
programming language by scanning how the data structure is actually
used, and part of it might have been entered by a programmer in 
specifying contraints on its use.  If I encounter a function I don't
understand, I might first pop up a window containing an English
description of the function and its purpose.  Then, if I need more,
I might look deeper and find a piece of pseudocode which I could
explode and find a formal specification of the code in a kind of
block diagram, each piece of which could be similarly expanded.  I 
could also easily find all the places where this function is used
by following links backwards.

Note that this doesn't abolish comments; if anything it makes them
foremost.

| NEVIN ":-)" LIBER  nevin1@ihlpb.ATT.COM  (312) 979-4751  IH 4F-410
-- 
		Stuart Ferguson		(shf@well.UUCP)
		Action by HAVOC

ssdken@jarthur.Claremont.EDU (Ken Nelson) (02/22/89)

In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:

>The question is:  Why?  From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare
>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.
>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.

Right, it is human nature.  However there is a way of ensuring good
documentation of C or any code. The technique is called the "review".  An
independant revview both of the code and the comments, and a software
managers insistence on fixing problems identified in the reviews, will
ensure proper documentation, and also raise the quality of the software
product.  All it takes is devoting a little up-front effort which will
yield large returns in the future as program complexity increases, and as
staff turnover makes orignial authors unavailable.

The reason "no one" wants to take the time to do it right is that "no one's"
team leader or manager did not require, enforce and provide incentives for
good documentation.  The problem is a people problem, not one of programming 
language, although certain languages do lend themselves to better 
documentation.

Software analysis tools can help by automating much of the header information
that becomes out of date (calls, called-by, change notices etc...).  Tools
are not a panacea, but merely a means of complementing a vigorous and 
strictly enforced documentation program that is  based on people doing 
their job correctly.


						Ken Nelson
						Principal Engineer
						Software Systems Design
						(714) 624-2306

In this case the views expressed above are shared by my employer.

perry@apollo.COM (Jim Perry) (02/22/89)

In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:
>In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes:
>
>>Let me begin by saying that I'm in the camp calling for more comments.
>
>I'm not.  I do agree with you on the problem (poor documentation), but
>I do not think that more comments is the answer.
>
>>Especially in the Unix/C world, the overwhelmingly vast majority of
>>programs are undercommented.  It's interesting that some aspects of
>>programming style, e.g. indentation, are fairly consistently applied,
>>while adequate documentation is the remote exception.
>
>The question is:  Why?  From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare
>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.
>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.
>
>Will requiring Joe Programmer to write more comments fix the situation?
>No.  

(examples of how Joe Programmer sleazes his way out of writing comments).

This attitude is one of the best arguments I've seen for distinguishing
Software Engineering from Programming.  Jane Engineer writes comments not
because someone is requiring her to, but because she knows that this
code is going to be around for a long time, and that the initial writing
is a tiny fraction of its lifetime.  Jane Engineer's had the pleasure of 
trying to modify a piece of Joe Programmer's undocumented code, and doesn't 
want the next person to work on her code use words like that about *her*.
For that matter, there's every chance that next person will be Jane herself
two years from now.  Joe's now selling shoes in Peoria, by the way.

"Rewrite their code into English" shows a basic misunderstanding.  Code
expresses some underlying algorithm which you should have thoroughly 
thought through before rendering it in C.  Your comments should be a
parallel rendering into English.  If anything, you should write
comments *first*.  Proper documentation naturally complements the code.

While it's true that there's no way of guaranteeing that comments agree 
with the code, the reverse is equally true.  If the comments are a good
English synopsis of the desired intent of the function, and the code
doesn't agree, there's every chance that the code is wrong.  If Joe
Programmer hacks up Jane Engineer's code without updating the comments, 
confusion can arise, but that's a worst-case scenario that's never bitten
me badly.

>This is the solution:  code should be self-documenting.  But,
>self-documenting is not the same as commenting!  When I change a line
>of code, my documentation should reflect that change automagically.  I
>don't get this with comments, and because of it, the only comments I
>rely on are my own personal ones.
>
>What is needed to improve self-documentation are better programming
>languages.

As you point out earlier, this is the Real World.  Some bright sunny day
we might have such languages, but the fact is we're stuck with C for quite
some time now, and C is more self-obfuscating that self-documenting; the
comments are all you've got.  
-- 
Jim Perry   perry@apollo.com    Apollo Computer, Chelmsford MA
This particularly rapid unintelligible patter isn't generally heard
and if it is it doesn't matter.

nevin1@ihlpb.ATT.COM (Liber) (02/22/89)

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

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

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

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

|After my experience 
|grading and after working with several large programs my conclusion is that
|well commented, self-documenting code is by far the best.  Also, forcing 
|an a-priori design and including this design in comments will not only
|produce higher quality and better designed programs but programs which are
|more easily understood since the structure of the software is documented.

I agree.  And the only way I see this happening is by making this
easier than the other, lazier alternatives.

|I agree entirely and advocate languages which allow direct expression of
|algorithms and design.  But since current languages are approaching that
|point and are not yet there, commenting is still necessary.

No argument here.

|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?
-- 
 _ __	NEVIN ":-)" LIBER  nevin1@ihlpb.ATT.COM  (312) 979-4751  IH 4F-410
' )  )			 "I will not be pushed, filed, stamped, indexed,
 /  / _ , __o  ____	  briefed, debriefed or numbered!  My life is my own!"
/  (_</_\/ <__/ / <_	As far as I know, these are NOT the opinions of AT&T.

hsd@uvacs.cs.Virginia.EDU (Harry S. Delugach) (02/22/89)

In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:
> From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare
>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.

What about the customer who wants to know why a certain multi-million dollar
company is taking so long to fix a reported bug in their software? What about
the teams of programmers who are trying to understand each other's code in
order to get the product out the door? 

>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.

I think the only way to get programmers to document their code is to convince
them that they gain tangible benefits from including comments in their code.
Sometimes it means having a programmer go back to a year-old program and
try to make efficient changes to it. Sometimes it means getting livid with
anger at the long-gone programmer when you have to maintain his/her 
uncommented code (Do unto others...). No one should include comments because
they're supposed to, or (egad!) required to. They should do it, in the words
of the TV commercial, because it's the right thing to do, like throwing your
trash in the trash can instead of littering.

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

>There are many instances on where poorly documented code is "worse than
>nothing"; most notably, when the comments are WRONG!  It has happened
>too many times that someone reads the comments on how the routine is
>"supposed to" work, makes a change, and finds out that the
>implementation is totally different than the comments.  I wonder how
>many lost man-years in software maintenance can be attributed to this.

Probably about the same number of person-hours taken up in going to and from
coffee machines in a million software developers' offices. :-) Seriously,
whenever I maintain code with such comments, I make a note to the effect that
the comments may be invalid. Sometimes, I just delete them entirely, so I
guess I agree that poor comments are worse than none. Clearly the best thing
is to add new comments when you make a change.

-- 
                              Harry S. Delugach   
Dept. of Computer Science, Univ. of Virginia, Charlottesville, VA 22901  U.S.A.
        INTERNET: hsd@cs.virginia.edu       BITNET: hsd2x@virginia
        UUCP: ..!uunet!virginia!uvacs!hsd   CIS: 72727,2363

EGNILGES@pucc.Princeton.EDU (Ed Nilges) (02/23/89)

In article <419ca3bc.183dc@apollo.COM>, perry@apollo.COM (Jim Perry) writes:

>
>(examples of how Joe Programmer sleazes his way out of writing comments).
>
>This attitude is one of the best arguments I've seen for distinguishing
>Software Engineering from Programming.  Jane Engineer writes comments not
>because someone is requiring her to, but because she knows that this
>code is going to be around for a long time, and that the initial writing
>is a tiny fraction of its lifetime.

     While I am in favor of highly literate, complete, and well-
     written comments, this posting places the blame for undercommented
     software on individual shoulders.  Far more important is the
     attitude of management.  In some situations, heavy use of
     "design methodologies" prior to coding have left little time
     for programmers to do other than crank out uncommented code.
     In others, management pressure for visible results selects out
     those programmers who neglect comments.

     Also, whether one is a programmer versus a software engineer is
     not a matter of personal virtue.  Traditional engineers were
     backed-up by legal, educational, and certification requirements,
     none of which apply to our field.  It is dangerous to allow
     management alone to define who is an engineer.  Finally, I'd
     appreciate talking to a good programmer over a person who
     (in the absence of legal/educational/certification requirements)
     pretends to be a "software engineer".

Edward Nilges

ALLE MENSCHEN WERDEN BRUDER - Schiller

rjh@cs.purdue.EDU (Bob Hathaway) (02/23/89)

(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

djones@megatest.UUCP (Dave Jones) (02/23/89)

From article <2989@uvacs.cs.Virginia.EDU>, by hsd@uvacs.cs.Virginia.EDU (Harry S. Delugach):

 [ On how to convince programmers to comment their code... ]

> Sometimes it means having a programmer go back to a year-old program and
>
> try to make efficient changes to it. Sometimes it means getting livid with
>                                                         ^^^^^^^ ^^^^^ ^^^^
> anger at the long-gone programmer when you have to maintain his/her 
> ^^^^^
> uncommented code (Do unto others...).

I almost never get mad any more. I've decided anger is out of place
except, perhaps,  when one is fighting other scavengers out on the savanna,
something I seldom do, now that the Safeway has opened up down the street.

But when I did get angry at programmers, it was never because they
did not comment their algorithms.  

Sometimes I got angry at them for writing convoluted code.  But when
I was deciphering that stuff, it seemed easier to read the tangled code than
to read the tangled comments. ( Somebody who has just written a mess of a
program probably will write a real big mess of a comment. )

And I *did* get angry when the comments did not match the code.  And I 
got *livid* when they did not comment the data-structures and variables.



                              Grrrrr,

                              Dave J.

djones@megatest.UUCP (Dave Jones) (02/23/89)

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.

ejp@abvax.icd.abnet.com (Ed Prochak) (02/23/89)

After reading several of the comments and replys I just felt some things
needed to be said. Since this is long, my main points are:
	*comments are necessary.
	*not inserting comments or not updating them is laziness.
	*not inserting or updating comments costs more money/time later on.
	*all it takes is a little commitment to do it right the first time.


In article <9689@ihlpb.ATT.COM> nevin1@ihlpb.ATT.COM (Liber) writes:

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

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

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

GOOD POINT. I know there are companies that do go back to the design
document and modify it to match implementation. One is my previous employer,
CompuGRAPHIC. What we did was to follow a hardware model. Just as the
electrical engineers developed their boards with revisions X1,X2, and so
on to initial product shipment, we did design baseline X1, code, test,
revise design to X2, and on. It isn't "painless", but it works superbly.
Code and design documents did diverge a little, but the differences were
usually covered in comments in the code. (The only major module we had
trouble with was the one that didn't follow this method.)
We had people switching responsibility of modules with
good results and a 2year project that was available for initial product
shipment in 18months. The point being that even under severe schedule
pressure, we did a decent job of maintaining the documentation.

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

EXACTLY. And the design can explain things that would be too verbose to put in
the code, such as operating system or performance constraints. Then the
comments in the source file can deal with the implementation issues, like
segmented memory and compiler limits.

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

Knuth has a system that allows this kind of development. I am looking
forward to trying it sometime. (when the schedule eases up a bit :^).

>|After my experience 
>|grading and after working with several large programs my conclusion is that
>|well commented, self-documenting code is by far the best.  Also, forcing 
>|an a-priori design and including this design in comments will not only
>|produce higher quality and better designed programs but programs which are
>|more easily understood since the structure of the software is documented.

>I agree.  And the only way I see this happening is by making this
>easier than the other, lazier alternatives.

Lazy is the word for it. but the lazyness is not only Joe's, it
includes Mike Manager's laziness in not seeing that the documentation
and commenting is done. As the sign on the restroom wall says
"the job is not finished until the paperwork is complete."

>|I agree entirely and advocate languages which allow direct expression of
>|algorithms and design.  But since current languages are approaching that
>|point and are not yet there, commenting is still necessary.

>No argument here.

I believe as some have stated in other followups that this will
not be possible. A programming language describes how to perform
some action, but the comments and design should give the why it
is being done.

>|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?
   -- 
I think it just takes commitment, by programmers and managers.
The initial investment in designing and commenting in the beginning
produces a large reduction in the cost of maintaining and enhancing
a system later. Not documenting is both lazy and inefficient.



--
Edward J. Prochak  Email: {cvedc,cwjcc,pyramid,decvax,masscomp,uunet}!abvax!ejp
                                             Allen-Bradley ICD
I think. I think I am. Therefore I AM!       747 Alpha Drive
         I think?  --- The Moody Blues       Highland Heights,OH 44143

billwolf@hubcap.clemson.edu (William Thomas Wolfe,2847,) (02/24/89)

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

gmg@yendor.UUCP (Gary Godfrey) (02/26/89)

From article <EJP.89Feb23100427@abvax.icd.abnet.com>, by ejp@abvax.icd.abnet.com (Ed Prochak):

[stuff deleted]

> Knuth has a system that allows this kind of development. I am looking
> forward to trying it sometime. (when the schedule eases up a bit :^).
> 

I assume you're referring to  _Literate_Programming_/Web?  I decided
at one point to attempt the same thing (in a MUCH more simplistic fashion)
under 'C'.  All I do is put the "program documentation" in my 'C'
comments in the form:

/*
 * miscl stuff...
 * .
 * .
 * %PDOC%
 *   * LATEX * commands + text can go here.
 * .
 * .
 * %ENDPDOC%
 */

Then all I have is a simple awk script that munges this stuff and converts
all the .c files to .tex files.  They are chained together by a single
file which ties the output files together and provides some cohesion.
It seemed to work well as an experiment.... The next thing that I want
to do (to take this a step further :-) is to implement what Stallman did
in gnu-emacs - put the On-line user documentation as part of the hard
documentation.  And further still, put the user docuemntation inside
the actual code.  So we then have something to the effect of:

/*
 * This is a function:
 * %UDOC%
 * Press the <enter> key at this point in order to bring up the widget
 * screen.  The F2 and F98 keys will envoke the goggle window and allow
 * you to spit 37 feet into the air.
 * %EUDOC%
 * %PDOC%
 * This implements the widget screen and goggle functions.  It does this
 * by flamming the dib cretan and tossing the b-span behind it's back.
 * %EPDOC%
 */

Not yet.....




> Edward J. Prochak  Email: {cvedc,cwjcc,pyramid,decvax,masscomp,uunet}!abvax!ejp

-----
If ever there was one, then I haven't seen it.  In fact, if there wasn't
one then I haven't seen it.  A->B !A->B.  B.  Damn.

Gary Godfrey - AVA Tech, Reston, VA             Phone:  (703)264-0074
UUCP: ..uunet!cyclops!media!yendor!gmg