21 Mar
2018
21 Mar
'18
8:17 p.m.
From: Larry McVoy <lm(a)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
21 Mar
21 Mar
9:03 p.m.
New subject: daemons are not to be exorcised
On Wed, Mar 21, 2018 at 10:17 AM, Noel Chiappa <jnc(a)mercury.lcs.mit.edu>
wrote:
Amen...
From: Larry
McVoy <lm(a)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.)
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
ᐧ
ᐧ
10:18 p.m.
New subject: daemons are not to be exorcised
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
11:28 p.m.
New subject: daemons are not to be exorcised
On 3/21/18, Arthur Krewat <krewat(a)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.
11:33 p.m.
New subject: daemons are not to be exorcised
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(a)gmail.com> wrote:
On 3/21/18, Arthur Krewat <krewat(a)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.
11:50 p.m.
New subject: daemons are not to be exorcised
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?
22 Mar
22 Mar
1:49 a.m.
New subject: daemons are not to be exorcised
On Mar 21, 2018 12:51 PM, "Arthur Krewat" <krewat(a)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.
1:37 a.m.
New subject: daemons are not to be exorcised
On 3/21/18, George Michaelson <ggm(a)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.
21 Mar
21 Mar
11:34 p.m.
New subject: daemons are not to be exorcised
On Wed, Mar 21, 2018 at 01:28:34PM -0400, Paul Winalski wrote:
On 3/21/18, Arthur Krewat <krewat(a)kilonet.net>
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".
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. 
22 Mar
22 Mar
8:24 a.m.
New subject: daemons are not to be exorcised
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."
21 Mar
21 Mar
11:39 p.m.
New subject: daemons are not to be exorcised
On Mar 21, 2018, at 1:28 PM, Paul Winalski
<paul.winalski(a)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
11:52 p.m.
New subject: daemons are not to be exorcised
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
11:56 p.m.
New subject: daemons are not to be exorcised
On 21 March 2018 at 13:28, Paul Winalski <paul.winalski(a)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.
22 Mar
22 Mar
12:01 a.m.
New subject: daemons are not to be exorcised
On Wed, Mar 21, 2018 at 01:56:38PM -0400, Nemo wrote:
On 21 March 2018 at 13:28, Paul Winalski
<paul.winalski(a)gmail.com>
wrote (in part):
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
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). 
12:04 a.m.
New subject: daemons are not to be exorcised
On Wed, Mar 21, 2018 at 1:28 PM, Paul Winalski <paul.winalski(a)gmail.com>
wrote:
On 3/21/18, Arthur Krewat <krewat(a)kilonet.net>
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.
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.
[...]
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.
1:56 a.m.
New subject: daemons are not to be exorcised
On Wed, Mar 21, 2018 at 2:04 PM, Dan Cross <crossd(a)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
ᐧ
2:04 a.m.
New subject: comments ( was daemons exorcised )
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
ᐧ
2:18 a.m.
New subject: comments ( was daemons exorcised )
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.
2:51 a.m.
New subject: comments ( was daemons exorcised )
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.
2:13 a.m.
New subject: daemons are not to be exorcised
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.
2:28 a.m.
New subject: Comments in early Unix systems
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
2:48 a.m.
New subject: Comments in early Unix systems
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.
4:18 a.m.
New subject: Comments in early Unix systems
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(a)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
5:02 a.m.
New subject: Comments in early Unix systems
On Wed, Mar 21, 2018 at 6:18 PM, William Corcoran <wlc(a)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
ᐧ
7:31 a.m.
New subject: Comments in early Unix systems
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(a)jctaylor.com> wrote:
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
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.
5:17 a.m.
New subject: Comments in early Unix systems
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
5:50 a.m.
New subject: Comments in early Unix systems
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".
6:55 a.m.
New subject: Comments in early Unix systems
On 03/21/2018 07:50 PM, Larry McVoy wrote:
On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur
Krewat wrote:
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
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".
7 a.m.
New subject: Comments in early Unix systems
On Wed, Mar 21, 2018 at 08:55:44PM -0400, Mike Markowski wrote:
On 03/21/2018 07:50 PM, Larry McVoy wrote:
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
On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur
Krewat wrote:
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 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". 
5:45 a.m.
New subject: Comments in early Unix systems
On Wed, Mar 21, 2018 at 2:28 PM, Warren Toomey <wkt(a)tuhs.org> wrote:
On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul
Winalski wrote:
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
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.
6:31 a.m.
New subject: Comments in early Unix systems
"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
6:58 a.m.
New subject: Comments in early Unix systems
On Wednesday, March 21, 2018, Warren Toomey <wkt(a)tuhs.org> wrote:
On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul
Winalski wrote:
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
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.
7:27 a.m.
New subject: Comments in early Unix systems
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
7:59 a.m.
New subject: Comments in early Unix systems
On Mar 21, 2018, at 6:27 PM, Larry McVoy <lm(a)mcvoy.com> wrote:
On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote:
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!
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. 
8:46 p.m.
New subject: Comments in early Unix systems
On 22 Mar 2018, at 01:27, Larry McVoy
<lm(a)mcvoy.com> wrote:
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
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 
9:22 p.m.
New subject: Comments in early Unix systems
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(a)quintile.net> wrote:
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
On 22 Mar 2018, at 01:27, Larry McVoy
<lm(a)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
10:22 p.m.
New subject: Comments in early Unix systems
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.
10:32 p.m.
New subject: Comments in early Unix systems
"Ron Natalie" <ron(a)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
23 Mar
23 Mar
2:20 a.m.
New subject: Comments in early Unix systems
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
22 Mar
22 Mar
10:33 p.m.
New subject: Comments in early Unix systems
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
23 Mar
23 Mar
7:31 a.m.
New subject: Comments in early Unix systems
On Wed, Mar 21, 2018 at 6:27 PM, Larry McVoy <lm(a)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
2466
days inactive
2468
days old
40 comments
26 participants
participants (26)
-
A. P. Garcia -
Andy Kosela -
arnold＠skeeve.com -
Arthur Krewat -
Bakul Shah -
Charles Anthony -
Clem Cole -
Dan Cross -
Dave Horsfall -
Earl Baugh -
George Michaelson -
jnc＠mercury.lcs.mit.edu -
Kurt H Maier -
Larry McVoy -
Lyndon Nerenberg -
Mike Markowski -
Nemo -
Paul Winalski -
ron minnich -
Ron Natalie -
Steve Johnson -
Steve Simon -
Warner Losh -
Warren Toomey -
WIlliam Cheswick -
William Corcoran