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

[TUHS] Comments in early Unix systems

[Doug McIlroy]

Thanks for the noweb story. A reward for straying off topic!

Doug

[TUHS] Comments in early Unix systems

[Noel Chiappa]

    > From: Warren Toomey <wkt at tuhs.org>

    > there is next to no commenting in the early code bases.

By 'early' you must mean the first 'C' PDP-11 Unixes, because certainly
starting with V6, it is reasonably well commented (to the point where I like
to say that I learned how to comment by reading the V6 code), e.g.:

  http://minnie.tuhs.org/cgi-bin/utree.pl?file=V6/usr/sys/ken/slp.c
  http://minnie.tuhs.org/cgi-bin/utree.pl?file=V6/usr/sys/dmr/bio.c

to pick examples from each author; and there are _some_ comments in the
assembler systems (both PDP-7 and PDP-11).

    > Given that the comments never made it into the compiled code, there was
    > no space reason to omit comments. There must have been another reason.

I was going to say 'the early disks were really small', but that hypothesis
fails because the very earliest versions (in assembler) do have some comments.

Although assembler is often so cryptic, the habit of putting a comment on each
instruction isn't so unreasonable.

So maybe the sort of comments one sees in assembler code (line-by-line
descriptions of what's happening; for subroutines, which arguments are in
which registers; etc) aren't needed in C code, and it took a while for them to
work out what sort of commenting _was_ appropriate/useful for C code?

The sudden appearance in V6 does make it seem as if there was a deliberate
decision to comment the code, and they went through it and added them in a
deliberate campaign.


    > From: Andy Kosela <akosela at andykosela.com>

    > "Practice of Programming" by Rob Pike and Brian Kernighan.
    > ...
    > They also state: "Comments ... do not help by saying things the code
    > already plainly says ... The best comments aid ... by briefly pointing
    > out salient details or by providing a larger-scale view of the
    > proceedings."

Exactly.

     Noel

[TUHS] Comments in early Unix systems

[Steve Nickolas]

On Wed, 21 Mar 2018, Noel Chiappa wrote:

> Although assembler is often so cryptic, the habit of putting a comment on each
> instruction isn't so unreasonable.
>
> So maybe the sort of comments one sees in assembler code (line-by-line
> descriptions of what's happening; for subroutines, which arguments are in
> which registers; etc) aren't needed in C code, and it took a while for them to
> work out what sort of commenting _was_ appropriate/useful for C code?

I tend to use more comments in my ASM than my C, for what it's worth. 
(Most of my coding lately has been in 6502 assembly.)

-uxo.

[TUHS] daemons are not to be exorcised

[Noel Chiappa]

    > From: Larry McVoy <lm at mcvoy.com>

    > Going forward, I wish that people tried to be simple as they tackle the
    > more complicated problems we have.

I have a couple of relevant quotations on my 'Some Computer-Related Lines'
page:

  "Deliberate complexity is the mark of an amateur. Elegant simplicity is the
  mark of a master."
	-- Unknown, quoted by Robert A. Crawford 

  "Fools ignore complexity. Pragmatists suffer it. Some can avoid it. Geniuses
  remove it."
	-- Alan Perlis

  "The most reliable components are the ones you leave out." 
	-- Gordon Bell

(For software, the latter needs to be read as 'The most bug-free lines of
codqe are the ones you leave out', of course.)


I remember watching the people building the LISP machine, and thinking 'Wow,
that system is complex'. I eventually decided the problem was that they were
_too_ smart. They could understand, and retain in their minds, all that
complexity.

	Noel

[TUHS] daemons are not to be exorcised

[Clem Cole]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2782 bytes --]

On Wed, Mar 21, 2018 at 10:17 AM, Noel Chiappa <jnc at mercury.lcs.mit.edu>
wrote:

>     > From: Larry McVoy <lm at mcvoy.com>
>
>     > Going forward, I wish that people tried to be simple as they tackle
> the
>     > more complicated problems we have.
>
> I have a couple of relevant quotations on my 'Some Computer-Related Lines'
> page:
>
>   "Deliberate complexity is the mark of an amateur. Elegant simplicity is
> the
>   mark of a master."
>         -- Unknown, quoted by Robert A. Crawford
>
>   "Fools ignore complexity. Pragmatists suffer it. Some can avoid it.
> Geniuses
>   remove it."
>         -- Alan Perlis
>
>   "The most reliable components are the ones you leave out."
>         -- Gordon Bell
>
> (For software, the latter needs to be read as 'The most bug-free lines of
> code are the ones you leave out', of course.)
>
​Amen...​




>
>
> I remember watching the people building the LISP machine, and thinking
> 'Wow,
> that system is complex'. I eventually decided the problem was that they
> were
> _too_ smart. They could understand, and retain in their minds, all that
> ​ ​
> complexity.

​And therein lies another interesting paradox... smart people don't always
realize that ​
​their being "smarter than the average bear" as it were, means mortals are
unlikely to be able to understand what you are doing.  Or more importantly,
your might not be that 'smart' later.

I'll never forget a conversation with one of my officemates at Masscomp who
had come from Steve Ward's group at MIT, who I will not name.  But he is
one the smartest people I ever worked with and someone I have tremendous
respect.   CMU used to have a required SW Engineering course and one of the
things drilled into us was commenting (you can usually tell code I worked
on by the dyslexia in my comments - but I do try to leave bit crumbs).​

Anyway, said person never had a such a course.  He says to me -- "Well I
only comment things I did not understand."   I looked at him in awe and
said:  "'Fred' -  you are one of the smartest people I know, please put the
comments in there for the rest of us."

A bit later, he got cut by his own sword.  He had had to pick up a piece of
code he had written a long time before and of course the context that he
had had when he wrote it was by that time completely lost.  Guess what - he
could not understand what the code was doing [BTW:  The last time I saw
something he wrote, he was wonderful at writing comments].

To me, "keep it short, simple, but always explain your intentions in prose"
need to be the guiding lights for programmers.

Clem
ᐧ
ᐧ
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/abc132e1/attachment.html>

[TUHS] daemons are not to be exorcised

[Arthur Krewat]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1794 bytes --]

On 3/21/2018 11:03 AM, Clem Cole wrote:
>
> To me, "keep it short, simple, but always explain your intentions in 
> prose" need to be the guiding lights for programmers.

It was instilled in me early on by my one and only mentor that someone 
that comes along later may have no idea what my code is doing. So 
comment. Even when it might be self-explanitory, comment anyway. This 
was on TOPS-10 back in the early 80's, usually MACRO-10 although I 
dabbled in ALGOL, SNOBOL, FORTRAN, etc.

When I look back at my own code, I can read the comments as the 
plot-line, so to speak, and the code itself just follows along.

I have noticed a lot of newer programmers these days that say 
(paraphrased): "Good code will explain itself" as a reason not to 
comment. Mostly C++ and Java programmers.

I call bullshit on that. Not commenting is lazy. There's no reason NOT 
to comment.

Most of my stuff has more comments byte-wise than real code. Something I 
wrote just yesterday as part of a much larger project:

// remove the UTF-8 BOM at the beginning of a line of text.
char bom[] = { 0xEF, 0xBB, 0xBF, 0 };                  // UTF-8 BOM
void remove_bom(char *str) {

     if (strncmp(str, bom, strlen(bom)) == 0) {         // can we find 
the BOM at the beginning of the line?
         strcpy(str, str + strlen(bom));             // yup, kill it.
     }
}

While that is definitely self-explanitory, I just can't help myself - 
and no, don't comment on my brazen assumptions of string length, or the 
fact that I assume it's UTF-8 - I've taken care of all of that 
elsewhere...  ;)

ak
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/d7cca4d3/attachment.html>

[TUHS] daemons are not to be exorcised

[Paul Winalski]

On 3/21/18, Arthur Krewat <krewat at kilonet.net> wrote:
>
> It was instilled in me early on by my one and only mentor that someone
> that comes along later may have no idea what my code is doing. So
> comment. Even when it might be self-explanitory, comment anyway.

In my 40-year career as a programmer, I've more than once had that
someone who comes along later be myself.

I also apply what I call the Bus Principle.  If you get hit by a bus
and killed, one of your colleagues is going to have to take over your
work.  Give them a fighting chance with code comments, and maybe even
a design document for large or complex things.

> I have noticed a lot of newer programmers these days that say
> (paraphrased): "Good code will explain itself" as a reason not to
> comment. Mostly C++ and Java programmers.
>
> I call bullshit on that. Not commenting is lazy. There's no reason NOT
> to comment.

Amen to that!  Good comments are one of the things that distinguishes
Software Engineering from mere programming.

-Paul W.

[TUHS] daemons are not to be exorcised

[Dan Cross]

On Wed, Mar 21, 2018 at 1:28 PM, Paul Winalski <paul.winalski at gmail.com>
wrote:

> On 3/21/18, Arthur Krewat <krewat at kilonet.net> wrote:
> > [...]
> > I call bullshit on that. Not commenting is lazy. There's no reason NOT
> > to comment.
>
> Amen to that!  Good comments are one of the things that distinguishes
> Software Engineering from mere programming.


Critical to that, however, is the adjective "good", as in "good comments."
Writing comments can be incredibly useful, but writing *good* comments is a
learned skill that requires judgement and taste.

Much ado is made nowadays about the "craft" of programming. I dislike this
analogy for a number of reasons, but there's no denying that good
programming has a craft element to it, and I claim that good commenting is
one of the harder of the craft skills to master. In particular, there *are*
good reasons NOT to comment something: the code is so obvious the comment
would just be a restatement of the manifestly evident, but with the added
visual clutter and cognitive load imposed by simply existing and the added
maintenance burden of being kept in sync. When I see a comment, I often
take it as an indication that something notable is happening: if the
comment is superfluous then I'm left wondering WHY it's there and what
about the code I'm missing. Similarly, comments must be maintained: my
experience is that out-of-date comments that have fallen out of sync with
the code are strictly a liability. Finding balance between the costs of
commenting and the positive benefits of comments takes time to develop.

When I was younger, I dressed somewhat better than I do now and when I was
in the Marines I once found myself in a social situation where it made
sense to wear a tweed jacket. Another Marine introduced me to the concept
of, "always, sometimes, never" vis which of the three buttons on the front
of my jacket to button: top button always, middle button sometimes, bottom
button never (whether this is good fashion advice or not is another
matter). I think that something analogous is true of writing good comments:

1. A comment should never simply parrot the code:  i++;  // Increment i.
2. A comment should sometimes explain *what* the code is doing.
3. A comment should always explain *why* the code is doing what it's doing.

Note that these are specific to comments, not to code: it does not follow,
for example, that a line or stanza of code should always be adorned with a
comment explaining why it exists: (think, `i++;  // Increment the array
index for the next iteration of the loop.` Ugh).

Btw, this is something I think that Unix did very well.

        - Dan C.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/29852f97/attachment.html>

[TUHS] daemons are not to be exorcised

[Clem Cole]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1039 bytes --]

On Wed, Mar 21, 2018 at 2:04 PM, Dan Cross <crossd at gmail.com> wrote:

>
> Critical to that, however, is the adjective "good", as in "good comments."
> Writing comments can be incredibly useful, but writing *good* comments is a
> learned skill that requires judgement and taste.
>
> ​....​
>
> 1. A comment should never simply parrot the code:  i++;  // Increment i.
> 2. A comment should sometimes explain *what* the code is doing.
> 3. A comment should always explain *why* the code is doing what it's doing.
>

i.e. there is a difference between: ​       i++;  // Increment i
*v.s.* the line: ​                      ptr->field++;  // ensure
reference count
stays sane

The former fails your first test, the second follows 2 & 3 as a note to my
future self that this is where I am doing the this piece of support work
(reference count maintenance).


Clem
ᐧ
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/6803fa6c/attachment.html>

[TUHS] daemons are not to be exorcised

[Paul Winalski]

Regarding comments, when I'm modifying code to fix a bug I find it
useful to insert a comment that references the bug's number in the bug
tracking system.  It can help answer the question "why is this code
here?" for someone reading the code later on, and sometimes it can
prevent regressions being introduced.

To bring this back to Unix, how well have the various commenting
principles we've been discussing been adhered to in the code base?

-Paul W.

[TUHS] Comments in early Unix systems

[Warren Toomey]

On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul Winalski wrote:
>To bring this back to Unix, how well have the various commenting
>principles we've been discussing been adhered to in the code base?

This is something that has bugged me forever.

The Unix design is simple and elegant. The manuals are lucid and
understandable. However, there is next to no commenting in the
early code bases. Why? [and I know ken is reading this]

Given that the comments never made it into the compiled code, there
was no space reason to omit comments. There must have been another
reason.

Cheers, Warren

[TUHS] Comments in early Unix systems

[Ron Natalie]

> Given that the comments never made it into the compiled code, there was no
space reason to omit comments. There must have been another reason.

Attitudes in software engineering have changed a lot over the 60 years we've
been programming.     Actually, UNIX was better than a lot of OS sources
I've dealt with.   Further, you had disk space and compile time issues to
worry about.

Amusingly, I worked with Mike Muuss for years (first at JHU and then at
BRL).   Mike believed much in putting comments on everything.    The DMR
"You're not expected to understand this" comment incensed him so much (yes I
know that's not what DMR meant) that he wrote an entire page to explain just
what retu/aretu/setka6 were doing there.

Amusingly, Mike was further incensed when Mike submitted a bunch of
revisions to BSD and McKusick, in the name of maintaining a uniform
commenting style, deleted all the comments.
I guess NONE is pretty consistent.

While this next anecdote strays from UNIX, I worked on a project my first
job out of college on a database system written in Fortran and Macro 11 on a
two-system RSX-11M+ system.    One of the early  projects there was to write
a program that counted "lines of code" to report to the customer progress or
something.     The head of software came up to the head database programmer
(not me) and said, "Do you know that we ran our line counter on your modules
and it said that there is only one line of comments in your entire module).
Jerry pointed out their software had to be in error, there weren't any lines
of comments.    In fact, a closer examination noted it counted one of the
MACRO-11 directives (.TITLE or something like that) as a comment.     In
Jerry's defense, there were comments in the code, just not lines that were
only comments.   They were just put at the end of the lines of existing
instructions.

[TUHS] Comments in early Unix systems

[William Corcoran]

Along the same lines:  

As UNIX *transitioned from the relative safety of academia (V7) into the cold, cruel  corporate world (System V), was there a corresponding effort to maintain and protect the UNIX codebase into a unified master repository with SCCS, for example?  

Is there any chance of finding a publicly available UNIX archive that includes the corresponding SCCS data for UNIX---to the extent that SCCS deltas and PRS comments can be examined?   

Bill Corcoran 

(*) IMHO


On Mar 21, 2018, at 4:28 PM, Warren Toomey <wkt at tuhs.org> wrote:

. . . 

Given that the comments never made it into the compiled code, there
was no space reason to omit comments. There must have been another
reason.

Cheers, Warren

[TUHS] Comments in early Unix systems

[Clem Cole]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 698 bytes --]

On Wed, Mar 21, 2018 at 6:18 PM, William Corcoran <wlc at jctaylor.com> wrote:

> Along the same lines:
> ​...
>
> Is there any chance of finding a publicly available UNIX archive that
> includes the corresponding SCCS data for UNIX---to the extent that SCCS
> deltas and PRS comments can be examined?
>
>
Bill check out Diomidis Spinellis truely amazing work at:
https://github.com/dspinellis/unix-history-repo

​He has done an amazing job of reconstructing much of the lost work.  It is
a treasure for us all.

Clem​


ᐧ
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/5c507626/attachment.html>

[TUHS] Comments in early Unix systems

[Larry McVoy]

On Wed, Mar 21, 2018 at 07:02:24PM -0400, Clem Cole wrote:
> On Wed, Mar 21, 2018 at 6:18 PM, William Corcoran <wlc at jctaylor.com> wrote:
> 
> > Along the same lines:
> > ???...
> >
> > Is there any chance of finding a publicly available UNIX archive that
> > includes the corresponding SCCS data for UNIX---to the extent that SCCS
> > deltas and PRS comments can be examined?
> >
> >
> Bill check out Diomidis Spinellis truely amazing work at:
> https://github.com/dspinellis/unix-history-repo
> 
> ???He has done an amazing job of reconstructing much of the lost work.  It is
> a treasure for us all.

Agreed but I'd still like the SCCS history.  I have it somewhere for BSD, it
was on Kirk's cds but I'd love to wander through the SCCS from Bell Labs.

I'm an SCCS fan, BitKeeper (sadly forgotten these days, my baby) was SCCS
on steriods.  BK has an import tool that will take SCCS history and intuit
what we today call commits, it will find the changes that are in the same
time and by the same person and create a changeset for that.  BK is still,
to this day, by far the best tool to use to browse history.  So if I could
get the SCCS history for early Unix I could give you all a super pleasant
way to look at that history (we open sourced BK when we shut down).

--lm

[TUHS] Comments in early Unix systems

[Arthur Krewat]

On 3/21/2018 6:18 PM, William Corcoran wrote:
> Given that the comments never made it into the compiled code, there
> was no space reason to omit comments. There must have been another
> reason.

I used to regularly compress sources of various distributions (not UNIX, 
but inn, pine, elm, etc) that I compiled, just to save space.

And that was in the early 90's when I could buy a 1GB SCSI drive for 
$1000. I can't imagine working off of the early hard drives...

ak

[TUHS] Comments in early Unix systems

[Larry McVoy]

On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur Krewat wrote:
> I used to regularly compress sources of various distributions (not UNIX, but
> inn, pine, elm, etc) that I compiled, just to save space.
> 
> And that was in the early 90's when I could buy a 1GB SCSI drive for $1000.
> I can't imagine working off of the early hard drives...

I was sys admin for a Masscomp with a 40MB disk and 20 users.  That
was, um, "fun".

[TUHS] Comments in early Unix systems

[Mike Markowski]

On 03/21/2018 07:50 PM, Larry McVoy wrote:
> On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur Krewat wrote:
>> I used to regularly compress sources of various distributions (not UNIX, but
>> inn, pine, elm, etc) that I compiled, just to save space.
>>
>> And that was in the early 90's when I could buy a 1GB SCSI drive for $1000.
>> I can't imagine working off of the early hard drives...
> 
> I was sys admin for a Masscomp with a 40MB disk and 20 users.  That
> was, um, "fun".

I remember Masscomp...  We used one (I forget model) in the field in the 
late 80s in the back of a tractor trailer.  We'd capture radar signals 
with it because it allowed data acquisition to not be swapped out.  It 
was a very expensive failure if, just as you started getting the short 
radar return, something like system logging swapped you out for a little!

Mike Markowski

[TUHS] Comments in early Unix systems

[Larry McVoy]

On Wed, Mar 21, 2018 at 08:55:44PM -0400, Mike Markowski wrote:
> On 03/21/2018 07:50 PM, Larry McVoy wrote:
> >On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur Krewat wrote:
> >>I used to regularly compress sources of various distributions (not UNIX, but
> >>inn, pine, elm, etc) that I compiled, just to save space.
> >>
> >>And that was in the early 90's when I could buy a 1GB SCSI drive for $1000.
> >>I can't imagine working off of the early hard drives...
> >
> >I was sys admin for a Masscomp with a 40MB disk and 20 users.  That
> >was, um, "fun".
> 
> I remember Masscomp...  We used one (I forget model) in the field in the
> late 80s in the back of a tractor trailer.  We'd capture radar signals with
> it because it allowed data acquisition to not be swapped out.  It was a very
> expensive failure if, just as you started getting the short radar return,
> something like system logging swapped you out for a little!

I remember the Masscomps we had fondly.  The ones we had were 68000 based
and they had two of those CPUs running in lock step (or something, Clem
will correct this, he was one of the main devs at Masscomp) because the
68K didn't do VM right.  I can't remember the details, it was something
like they didn't handle faults right so they ran two CPUs and when the 
fault happened the 2nd CPU somehow got involved.

Clem, what model was that?  And can you provide the real version of what
I was trying say?

--lm

[TUHS] Comments in early Unix systems

[Warner Losh]

On Wed, Mar 21, 2018 at 2:28 PM, Warren Toomey <wkt at tuhs.org> wrote:

> On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul Winalski wrote:
>
>> To bring this back to Unix, how well have the various commenting
>> principles we've been discussing been adhered to in the code base?
>>
>
> This is something that has bugged me forever.
>
> The Unix design is simple and elegant. The manuals are lucid and
> understandable. However, there is next to no commenting in the
> early code bases. Why? [and I know ken is reading this]
>
> Given that the comments never made it into the compiled code, there
> was no space reason to omit comments. There must have been another
> reason.
>

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've never been able to verify this story, but it came from someone
who started with v5. Sadly, he passed away 15 years ago, or I'd just ask
him again...

Warner
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/33017e3a/attachment.html>

[TUHS] Comments in early Unix systems

[Steve Johnson]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2921 bytes --]



"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've never been able to verify this
story, but it came from someone who started with v5. Sadly, he passed
away 15 years ago, or I'd just ask him again..."

Ah, the consent decree.   The basic idea of the consent decree was
to prevent AT&T's regulated monopoly from giving it an unfair
advantage in other areas.   And, since the regulation guaranteed a
rate of return, certain restrictions were put on the ability of AT&T
to do business outside of the telephone arena.  In particular, one
requirement was that AT&T MUST patent anything they did that was
patentable.  And furthermore, they must license that patent to all
comers at a "reasonable" rate.

The decree was signed in 1956.   And then, along came software! 
AT&T foundi itself required to patent software inventions at a time
that nobody was sure what that meant, or whether software was even
patentable.  There were some very strange patents, or at least patent
applications, that came out of this.  I remember an algorithm for
generating permutations that was recast as a relay computer because
that was probably patenable and, if so, AT&T had to do it.  

Also, the mindset of AT&T was to plan in 20 year timescales, and they
had trouble understanding the increasing speed of software
innovation.  The patent department's attitude about a lot of the
issues of Unix licensing, etc., was basically to wait 5 years until
there was some precedent before acting.  Meanwhile, when they took an
interest they would issue some directive, often to reverse themselves
several months later.  I remember before one of the releases we had
to make sure we had a copyright notice on every file, only to be told
six months later to make sure that we removed all copyright notices
from all files.

One run-in that I had with the legal team happened just as Unix and C
were beginning to become popular, and some new C compilers were
appearing.  I made a strong appeal, with the support of my
management, to release the front end of PCC (or at least the Yacc
grammar for C) into the public domain, to try to encourage some
consistency in what we intended to be a portable language.  Meetings
dragged on for months, and we were finally told no.   I don't know
whether, had I been successfu, we could have avoided all the ANSI /
Posix confusion that came later, or at least limit the number of
incompatibilities that rapidly appeared in "C" compilers.  But it
might have helped...

Steve


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/93737de3/attachment.html>

[TUHS] Comments in early Unix systems

[Andy Kosela]

On Wednesday, March 21, 2018, Warren Toomey <wkt at tuhs.org> wrote:

> On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul Winalski wrote:
>
>> To bring this back to Unix, how well have the various commenting
>> principles we've been discussing been adhered to in the code base?
>>
>
> This is something that has bugged me forever.
>
> The Unix design is simple and elegant. The manuals are lucid and
> understandable. However, there is next to no commenting in the
> early code bases. Why? [and I know ken is reading this]
>
> Given that the comments never made it into the compiled code, there
> was no space reason to omit comments. There must have been another
> reason.
>
>
I think some answers could be find in "Practice of Programming" by Rob Pike
and Brian Kernighan.  In the section about comments they express why they
are not big fans of verbose commenting style.

They also state: "Comments are meant to help the reader of a program.  They
do not help by saying things the code already plainly says, or by
contradicting the code, or by distracting the reader with elaborate
typographical displays.  The best comments aid the understanding of a
program by briefly pointing out salient details or by providing a
larger-scale view of the proceedings."

--Andy
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/13e55582/attachment.html>

[TUHS] Comments in early Unix systems

[Larry McVoy]

On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote:
> They also state: "Comments are meant to help the reader of a program.  They
> do not help by saying things the code already plainly says, or by
> contradicting the code, or by distracting the reader with elaborate
> typographical displays.  The best comments aid the understanding of a
> program by briefly pointing out salient details or by providing a
> larger-scale view of the proceedings."

I so agree with this.  Verbose comments suck.  Too many comments suck.
Why?  Because the code evolves and it's work to evolve the comments
as well.  Too many comments means they are not maintained and they 
become incorrect.

I *HATE* comments that are not correct, hate that so much that if you did
that we would talk, if you kept doing that, you are fired.  No comments
are MUCH better than incorrect comments.

Terseness in comments is good.  Comment where it is not obvious what
is going on.  And maintain the comments like you maintain the code.

I agree with Dan (I think) that coding is still a craft and getting the
comments right is one of the hardest things to master (and I agree that
Unix did it pretty darn well).  No comments suck, too much sucks, just
right is so darn pleasant.

--lm

[TUHS] Comments in early Unix systems

[Bakul Shah]

On Mar 21, 2018, at 6:27 PM, Larry McVoy <lm at mcvoy.com> wrote:
> 
> On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote:
>> They also state: "Comments are meant to help the reader of a program.  They
>> do not help by saying things the code already plainly says, or by
>> contradicting the code, or by distracting the reader with elaborate
>> typographical displays.  The best comments aid the understanding of a
>> program by briefly pointing out salient details or by providing a
>> larger-scale view of the proceedings."
> 
> I so agree with this.  Verbose comments suck.  Too many comments suck.
> Why?  Because the code evolves and it's work to evolve the comments
> as well.  Too many comments means they are not maintained and they 
> become incorrect.
> 
> I *HATE* comments that are not correct, hate that so much that if you did
> that we would talk, if you kept doing that, you are fired.  No comments
> are MUCH better than incorrect comments.
> 
> Terseness in comments is good.  Comment where it is not obvious what
> is going on.  And maintain the comments like you maintain the code.
> 
> I agree with Dan (I think) that coding is still a craft and getting the
> comments right is one of the hardest things to master (and I agree that
> Unix did it pretty darn well).  No comments suck, too much sucks, just
> right is so darn pleasant.

When reading new code, I initially ignore comments,
at least within a function, and just try to figure
out what the code does. This is because often people
do not update comments. Code has to at least compile
so they are forced to update it and hopefully test
it but comments....

In the Go language ecosystem they have "go doc" which
can pull out comments at different level. Example:

go doc io // package level + top level exported declarations
go doc io.Copy // function level comments + header
go doc io.Reader // interface level + interface body

and so on. This does incentivize people to write good
comments.  This is very handy in that you can see how
your comments read when divorced from the code. But
notice that no comments within a function are output.
[Perhaps IDEs show relevant comments too but I find
them too heavyweight and don't use them]

A larger point is appropriate documentation, not just
source comments. There should be a function spec as
well. I used to write a manpage for a command etc.
first, especially when someone else has to code it.
A manpage is describes the syntax, function, results
and errors and links to related manpages. All this
usually in a page or two!

[TUHS] Comments in early Unix systems

[Steve Simon]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1717 bytes --]



> On 22 Mar 2018, at 01:27, Larry McVoy <lm at mcvoy.com> wrote:
> 
>> On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote:
>> They also state: "Comments are meant to help the reader of a program.  They
>> do not help by saying things the code already plainly says, or by
>> contradicting the code, or by distracting the reader with elaborate
>> typographical displays.  The best comments aid the understanding of a
>> program by briefly pointing out salient details or by providing a
>> larger-scale view of the proceedings."
> 
> I so agree with this.  Verbose comments suck.  Too many comments suck.
> Why?  Because the code evolves and it's work to evolve the comments
> as well.  Too many comments means they are not maintained and they 
> become incorrect.
> 
> I *HATE* comments that are not correct, hate that so much that if you did
> that we would talk, if you kept doing that, you are fired.  No comments
> are MUCH better than incorrect comments.
> 
> Terseness in comments is good.  Comment where it is not obvious what
> is going on.  And maintain the comments like you maintain the code.
> 
> I agree with Dan (I think) that coding is still a craft and getting the
> comments right is one of the hardest things to master (and I agree that
> Unix did it pretty darn well).  No comments suck, too much sucks, just
> right is so darn pleasant.
> 
> --lm

on the commenting subject, and as it was Shannon’s anniversary recently... i always felt information theory relates well to comments.

i.e. repeating anything i can see from the code (like “returns void”) tells me nothing.

telling me something non-obvious (“allocate one more for end of list sentinel”)  really helps.

-Steve

[TUHS] Comments in early Unix systems

[ron minnich]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2345 bytes --]

so if you had an 11/45 with dual RKO5s back in the day with their massive
storage capacity, then you had source and your system with source and docs
could run out of L2 cache in a modern cheapo IOT board.

Now wouldn't that be a hoot. But how would we simulate pulling the RK05
cartridge out of the drive?

On Thu, Mar 22, 2018 at 8:05 AM Steve Simon <steve at quintile.net> wrote:

>
>
> > On 22 Mar 2018, at 01:27, Larry McVoy <lm at mcvoy.com> wrote:
> >
> >> On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote:
> >> They also state: "Comments are meant to help the reader of a program.
> They
> >> do not help by saying things the code already plainly says, or by
> >> contradicting the code, or by distracting the reader with elaborate
> >> typographical displays.  The best comments aid the understanding of a
> >> program by briefly pointing out salient details or by providing a
> >> larger-scale view of the proceedings."
> >
> > I so agree with this.  Verbose comments suck.  Too many comments suck.
> > Why?  Because the code evolves and it's work to evolve the comments
> > as well.  Too many comments means they are not maintained and they
> > become incorrect.
> >
> > I *HATE* comments that are not correct, hate that so much that if you did
> > that we would talk, if you kept doing that, you are fired.  No comments
> > are MUCH better than incorrect comments.
> >
> > Terseness in comments is good.  Comment where it is not obvious what
> > is going on.  And maintain the comments like you maintain the code.
> >
> > I agree with Dan (I think) that coding is still a craft and getting the
> > comments right is one of the hardest things to master (and I agree that
> > Unix did it pretty darn well).  No comments suck, too much sucks, just
> > right is so darn pleasant.
> >
> > --lm
>
> on the commenting subject, and as it was Shannon’s anniversary recently...
> i always felt information theory relates well to comments.
>
> i.e. repeating anything i can see from the code (like “returns void”)
> tells me nothing.
>
> telling me something non-obvious (“allocate one more for end of list
> sentinel”)  really helps.
>
> -Steve
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180322/1fcbb6ff/attachment-0001.html>

[TUHS] Comments in early Unix systems

[Ron Natalie]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 564 bytes --]


 

>  i.e. repeating anything i can see from the code (like “returns void”) tells me nothing.

It's right up there with using #defines for silly things like
    #define FOUR 4

Great.   What doe this tell me that the literal 4 doesn't.    It's a matter of time until someone says
    #define FOUR 5

I actually found some code in use that had

#define notdef 1

in it.    I about went through the roof.

Frankly, I have immense distaste for the definition NULL.    Especially those implementations that try to fix it by introducing a spurious cast on it.

[TUHS] Comments in early Unix systems

[arnold]

"Ron Natalie" <ron at ronnatalie.com> wrote:

> Frankly, I have immense distaste for the definition NULL.    Especially
> those implementations that try to fix it by introducing a spurious cast
> on it.

I'll agree with the latter part. But in my own code I try to be very
careful to use NULL for pointers, '\0' for end of string, and 0 for
numbers. Even though 0 could be used in all three cases, the different
forms make it much more clear what the type of data is that I'm working
with.

My two cents,

Arnold

[TUHS] Comments in early Unix systems

[Lyndon Nerenberg]

> I'll agree with the latter part. But in my own code I try to be very
> careful to use NULL for pointers, '\0' for end of string,

In the '\0' case I have a preference for NUL, but admittedly it's easy to 
confuse/typo with NULL.  That convention follows from my habit of enuming 
ASCII constants with their three-letter 'names' (e.g. CAN, DLE, ...).

--lyndon

[TUHS] Comments in early Unix systems

[Kurt H Maier]

On Thu, Mar 22, 2018 at 12:22:06PM -0400, Ron Natalie wrote:
> 
> It's right up there with using #defines for silly things like
>     #define FOUR 4
> 
> Great.   What doe this tell me that the literal 4 doesn't.    It's a matter of time until someone says
>     #define FOUR 5
> 

One of my favorite messages I've ever received:
          
http://sourceware.org/ml/glibc-cvs/2013-q1/msg00115.html
          
khm

[TUHS] Comments in early Unix systems

[Charles Anthony]

On Wed, Mar 21, 2018 at 6:27 PM, Larry McVoy <lm at mcvoy.com> wrote:

>
> I *HATE* comments that are not correct, hate that so much that if you did
> that we would talk, if you kept doing that, you are fired.  No comments
> are MUCH better than incorrect comments.
>
>
From "Programming Pearls": "If the code and the comments disagree, they are
probably both wrong."

-- Charles
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180322/aba87c4a/attachment.html>