Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!rutgers!netsys!lamc!well!shf
From: shf@well.UUCP (Stuart H. Ferguson)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <10782@well.UUCP>
Date: 20 Feb 89 10:14:23 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Reply-To: shf@well.UUCP (Stuart H. Ferguson)
Organization: The Blue Planet
Lines: 109


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