[TUHS] daemons are not to be exorcised

[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

[George Michaelson]

I think there's a middle ground. saying "this is a loop" is not
informative. saying "I did this as a loop because..." can be very
informative.

I think with short circuit evaluation and side-effects in C, this kind
of code is especially worth commenting: people need to remember the
right hand side of a complex set of expressions might actually not
have done anything.

Here at IETF a really cute corner-case of optimization-for-bug came
up. Somebody who thought they had worked out a given packet in UDP dns
messages always had a pair of specific chars 0x0c and 0xc0 in sequence
(or something) and coded for it, not realizing they were coding below
the outcome of a DNS label compression pattern which didn't always
hold. Sometimes, people code from faulty or incomplete information. So
this one, (for instance) would have been much better commented than
not.

It would have let the following people hit the coder with a thin whippy stick.

On Wed, Mar 21, 2018 at 5:28 PM, Paul Winalski <paul.winalski at gmail.com> wrote:
> 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

[Larry McVoy]

On Wed, Mar 21, 2018 at 01:28:34PM -0400, Paul Winalski wrote:
> 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.

Yep.  Someone once told me "any code that you wrote more than 6 months
ago might as well have been written by someone else.  So write it in a
way that you can debug it".

[TUHS] daemons are not to be exorcised

[WIlliam Cheswick]

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


> On Mar 21, 2018, at 1:28 PM, Paul Winalski <paul.winalski at gmail.com> wrote:
> 
> In my 40-year career as a programmer, I've more than once had that
> someone who comes along later be myself.

“Comments are love letters we write to our future selves.”
 - Jon Bentley

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

[TUHS] daemons are not to be exorcised

[Arthur Krewat]

On 3/21/2018 1:33 PM, George Michaelson wrote:
> I think there's a middle ground. saying "this is a loop" is not
> informative. saying "I did this as a loop because..." can be very
> informative.
Absolutely. Using my "comments as the plot" analogy, that would be like 
the main character in a movie saying "this is a chair" instead of "this 
is my dad's chair".

So much more meaning ;)

And bringing it back to UNIX, I remember reading here on this list that 
comments were sanitized, removing any humor. Anyone got any good 
examples of that?

[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: 345 bytes --]

On 3/21/2018 1:39 PM, WIlliam Cheswick wrote:
>
> “Comments are love letters we write to our future selves.”
>  - Jon Bentley

Truth be told, I sometimes get into a melancholy state, and go back to 
code I wrote decades ago just to go through the history section and 
remind myself why I got into this line of work in the first place.

ak

[TUHS] daemons are not to be exorcised

[Nemo]

On 21 March 2018 at 13:28, Paul Winalski <paul.winalski at gmail.com>
wrote (in part):
> 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.

A manager insisted that everyone spend the last 15min of the day
writing down what was done that day on a sheet of paper and putting in
your desk drawer.  No one was run over by a bus but the paper became
the first thing many consulted next day (and the act of writing
consolidated thoughts -- something much lost today).

N.

[TUHS] daemons are not to be exorcised

[Larry McVoy]

On Wed, Mar 21, 2018 at 01:56:38PM -0400, Nemo wrote:
> On 21 March 2018 at 13:28, Paul Winalski <paul.winalski at gmail.com>
> wrote (in part):
> > 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.
> 
> A manager insisted that everyone spend the last 15min of the day
> writing down what was done that day on a sheet of paper and putting in
> your desk drawer.  No one was run over by a bus but the paper became
> the first thing many consulted next day (and the act of writing
> consolidated thoughts -- something much lost today).

I'd like a $repo/src/STATE file filled out at the end of my day.  Back in
the day I had a coworker that would do a 

	find /home/bk/lm -maxdepth 3 -name STATE -mtime -1

in the morning to see what I had been up to :)

The act of dumping what I was trying to do, what I had figured out so far,
just dumping state, frequently lead to the solution.  So it had the "bad"
effect of making me work longer to actually finish.

I've worked on problems in the kernel that were hard enough that it could
take me as much as 8 hours of thinking to get back to where I was yesterday.
The STATE file came out of that, it ramped me up faster.

--lm

[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

[Paul Winalski]

On 3/21/18, George Michaelson <ggm at algebras.org> wrote:
>
> I think with short circuit evaluation and side-effects in C, this kind
> of code is especially worth commenting: people need to remember the
> right hand side of a complex set of expressions might actually not
> have done anything.
>
One thing that is always worth a comment is Perl regular expressions.
A prose description of what the regex is supposed to match can save
someone else a lot of time.

-Paul W.

[TUHS] daemons are not to be exorcised

[A. P. Garcia]

On Mar 21, 2018 12:51 PM, "Arthur Krewat" <krewat at kilonet.net> wrote:

On 3/21/2018 1:33 PM, George Michaelson wrote:

> I think there's a middle ground. saying "this is a loop" is not
> informative. saying "I did this as a loop because..." can be very
> informative.
>
Absolutely. Using my "comments as the plot" analogy, that would be like the
main character in a movie saying "this is a chair" instead of "this is my
dad's chair".

So much more meaning ;)

And bringing it back to UNIX, I remember reading here on this list that
comments were sanitized, removing any humor. Anyone got any good examples
of that?


Well, I remember many years ago seeing a comment in the Linux kernel to the
effect that the kernel would never be larger than 2 MB IIRC. Which to me is
kind of humorous in retrospect.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/2a9bcb35/attachment-0001.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] comments ( was daemons exorcised )

[Earl Baugh]

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

I remember seeing a fortune or the like that said :

Documentation is like sex. When it’s good its very very good. When it’s  bad, it’s better than nothing. 

I found many times this rule applies to comments I’ve encountered in difficult code I’ve had the chore in debugging. :-) 

Earl 

Sent from my iPhone
> ᐧ
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/fb6d6e79/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 ( was daemons exorcised )

[Paul Winalski]

A co-worker of mine once had a particularly nasty time debugging a
customer bug.  When he finally tracked down the faulty code, it was
preceded by a comment that said, "Someday someone will hate me for
this."

-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 ( was daemons exorcised )

[Ron Natalie]

Having been a supervisor of a large software package of which there were programmers of all skill levels I would periodically review the software.
Every once and a while I would note something that needed to be fixed by putting the comment "BOGUS" on that region.      Depending on out bad it was, the number of Os in BOGUS would increase.
My second-in-command realized this one section needed to be rewritten when it was marked BOOOOOOOOOOOOGUS.

[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

[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

[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

[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

[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

[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

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

[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

[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

[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] daemons are not to be exorcised

[Dave Horsfall]

On Wed, 21 Mar 2018, Larry McVoy wrote:

> Yep.  Someone once told me "any code that you wrote more than 6 months 
> ago might as well have been written by someone else.  So write it in a 
> way that you can debug it".

Yep, and I'm glad that I had bosses to whom I didn't have to explain why 
my comments were so voluminous.

And who first said "Write your code as though the next person to maintain 
it is a psychotic axe-wielding murderer who knows where you live"?  I've 
often thought that way (as the murderer I mean, not the murderee).

I'd name names, but he might be on this list...

-- 
Dave Horsfall DTM (VK2KFU)  "Those who don't understand security will suffer."

[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

[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

[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

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