[TUHS] Comments in early Unix systems

[TUHS] Comments in early Unix systems

[Doug McIlroy]

"I was told in school (in 1985) that if I was ever lucky enough to
have access to the unix source, I'd find there were no comments. The
reason, I was told at the time, was that comments would make the
source code useful, and selling software was something AT&T couldn't
do due to some consent decree."

I can't speak for SYS V, but no such idea was ever mentioned in
Research circles. Aside from copyright notices, the licensing folks
took no interest in comments. Within rsearch there was tacit
recognition of good coding style--Ken's cut-to-the-bone code was
universally admired. This cultural understanding did not extend
to comments. There was disparagement for the bad, but not honor
for the good. Whatever comments you find in the code were put
there at the author's whim.

My own commenting style is consistent within a project, but
wildly inconsistent across projects, and not well correlated
with my perception of the audience I might be writing for.
Why? I'm still groping for the answer.

For imoortant code, custom is to describe it in a separate
paper, which is of course not maintained in parallel with
the code. In fact, comments are often out of date, too.
Knuth offered the remedy of "literate programming", which
might help in academic circles. In business, probably not.
Yet think of the possibility of a "literate spec", where
the code grows organically with the understanding of what
has to be done.

Doug

[TUHS] Comments in early Unix systems

[Nemo]

On 22/03/2018, Doug McIlroy <doug at cs.dartmouth.edu> wrote:
[...]
> For imoortant code, custom is to describe it in a separate
> paper, which is of course not maintained in parallel with
> the code. In fact, comments are often out of date, too.
> Knuth offered the remedy of "literate programming", which
> might help in academic circles. In business, probably not.
> Yet think of the possibility of a "literate spec", where
> the code grows organically with the understanding of what
> has to be done.

At a previous company, we used Ramsey's noweb with good results.  The
code was very heavy in math;  being able to read the typeset
explanation alongside the code was very helpful, especially for
understanding the optimization transformations.  (We also began to
include Xfig diagrams to document data flow and so on.) The next
manager decided to describe the code in separate documents, with mixed
results.  In hindsight, I probably would not have used noweb on the
typical stuff but I would definitely use noweb again to document the
math-intensive stuff.

N.

>
> Doug
>

[TUHS] Literate Programming (was Comments in early Unix systems)

[arnold]

Doug McIlroy <doug at cs.dartmouth.edu> wrote:

> Knuth offered the remedy of "literate programming", which
> might help in academic circles. In business, probably not.

IMHO this is too bad. Code I've written using LP is generally 
more correct earlier on than otherwise. And it's very enjoyable
to write code and explanation at the same time; I feel like I'm
talking out loud directly to my reader, a person, and not just
coding for myself or the compiler.

Significant proofs by example are Knuth's TeX and MetaFont,
and the lcc compiler by Dave Hanson and <I forgot>.

Shameless plug: I have written a small LP system in gawk designed
for use with the Texinfo markup language. It is written using itself.
I have written two other good size awk scripts using it as well.
I think it will scale well to larger stuff in C or C++ but simply
have not had an opportunity to use it for anything like that yet.

See https://github.com/arnoldrobbins/texiwebjr if interested;
and feel free to follow up privately instead of on the list to keep
things on topic.

Thanks,

Arnold

[TUHS] Literate Programming (was Comments in early Unix systems)

[Jon Steinhart]

arnold at skeeve.com writes:
> Doug McIlroy <doug at cs.dartmouth.edu> wrote:
>
> > Knuth offered the remedy of "literate programming", which
> > might help in academic circles. In business, probably not.
>
> IMHO this is too bad. Code I've written using LP is generally 
> more correct earlier on than otherwise. And it's very enjoyable
> to write code and explanation at the same time; I feel like I'm
> talking out loud directly to my reader, a person, and not just
> coding for myself or the compiler.
>
> Significant proofs by example are Knuth's TeX and MetaFont,
> and the lcc compiler by Dave Hanson and <I forgot>.
>
> Shameless plug: I have written a small LP system in gawk designed
> for use with the Texinfo markup language. It is written using itself.
> I have written two other good size awk scripts using it as well.
> I think it will scale well to larger stuff in C or C++ but simply
> have not had an opportunity to use it for anything like that yet.
>
> See https://github.com/arnoldrobbins/texiwebjr if interested;
> and feel free to follow up privately instead of on the list to keep
> things on topic.
>
> Thanks,
>
> Arnold

In mid-1985 I independently had the idea that combining code and
documentation would make it easier to keep them in sync.  I wrote
a program called "xman" for "eXtract MAN pages" that generated troff
man pages from special comments that began with /**.  A few months
later I got a course proposal accepted by SIGGRAPH and asked James
Gosling to participate.  During one of our get-togethers I showed
him xman.  While correlation doesn't equal causation (and James
doesn't remember), /** reappeared in JavaDoc which spread like the
plague to doxygen et. al.

We abandoned xman after a few months.  It was an interesting experiment,
but was only "useful" for producing large volumes of nicely typeset
utterly irrelevant documentation.  Which, of course, since many others
have since drunk the Kool-Aid, is the state of much documentation today.

What works for me documentation wise-is:

 o  Block comments that say what the code does, not how it does it unless
    it's not obvious from looking at the code.

 o  Inline or block comments for things that aren't obvious.

 o  Separate BTL-style document that explains what the program does,
    describes the data structures, and how the different parts of the
    program manipulate those structures.  Sometimes that can go in a
    code file if it's a small and simple program.

While I'm at it, my two cents on the NULL topic.  I use '\0' for NUL
as that's not the same as NULL.  When I want NULL, I always cast it,
for example, (struct foo *)0 because that locally provides some often
non-local information about the type of the things that's being compared
or set to NULL.

Jon

[TUHS] Literate Programming (was Comments in early Unix systems)

[Toby Thain]

On 2018-03-22 12:30 PM, arnold at skeeve.com wrote:
> Doug McIlroy <doug at cs.dartmouth.edu> wrote:
> 
>> Knuth offered the remedy of "literate programming", which
>> might help in academic circles. In business, probably not.
> 
> IMHO this is too bad. Code I've written using LP is generally 
> more correct earlier on than otherwise. And it's very enjoyable
> to write code and explanation at the same time; I feel like I'm
> talking out loud directly to my reader, a person, and not just
> coding for myself or the compiler.
> 
> Significant proofs by example are Knuth's TeX and MetaFont,
> and the lcc compiler by Dave Hanson and <I forgot>.

Chris Fraser (AT&T Bell Labs at the time).

As you say, the whole book is a literate program:
https://www.pearson.com/us/higher-education/program/Hanson-Retargetable-C-Compiler-A-Design-and-Implementation/PGM166351.html


> 
> Shameless plug: I have written a small LP system in gawk designed
> for use with the Texinfo markup language. ...
> Thanks,
> 
> Arnold
>