history of comments and source code annotations
Michael Wojcik
conference of the Association of Teachers of Technical Writing about
programming as technical writing. Since programmers often have to read
source code, they're as much an audience for it as the compiler is,
and so writing code can be seen as an exercise in technical writing.
Of course many people have noticed this and responded to it, and so
part of my talk will be about efforts to make code readable, from
comments, to attempts at readable languages, to in-code documentation
(Javadoc, Doxygen, etc), to Knuth's literate programming.
I'm wondering if anyone knows of any sources of histories - formal or
anecdotal - for things like the introduction of source-code comments
in the early era of stored-program computers. I have some bits and
pieces, but I'm always looking for other interesting tidbits I could
throw in.
--
Michael Wojcik
Micro Focus
Rhetoric & Writing, Michigan State University
Stan Barr
>
> I'm wondering if anyone knows of any sources of histories - formal or
> anecdotal - for things like the introduction of source-code comments
> in the early era of stored-program computers. I have some bits and
> pieces, but I'm always looking for other interesting tidbits I could
> throw in.
>
comments. Whether they were written at the time, which seems likely, or
added later I can't say.
See: http://www.dcs.wawrwick.ac.uk/~edsac/ and look at the tutorial guide.
Some other docs in the links section.
--
Cheers,
Stan Barr plan.b .at. dsl .dot. pipex .dot. com
The future was never like this!
jmfbahciv
One of Peter Conklin's grandiose ideas, which never ended up working
well, was to have the comments in MACRO-10 source code be "encoded"
with RUNOFF commands. He modified RUNOFF to ignore the code and
use the coments (minus the ;) as its input. What should have
been spit out was a foo.DOC (but that's the wrong extension I think)
which should have been the real documentation for each MACRO-10
source file.
If you want to see an example, get the files SCAN.MAC and WILD.MAC.
Conklin wrote those while he was advocating this scheme of his.
It would have been nice. All the technical writers would have had
to do, to produce a technical manual for New Bedford, would run
the source through RUNOFF. However, most of our programmers did
not have the typesetting style of thinking.
/BAH
jmfbahciv
Sorry, I forgot to tell you where you can find SCAN.MAC and WILD.MAC.
They were shipped on the CUSP tape for TOPS-10. I don't remember
which TOPS-20 tape had them. Maybe Mark can point you to them.
/BAH
Peter Flass
> On Sat, 07 Feb 2009 17:15:54 -0500, Michael Wojcik <mwo...@newsguy.com> wrote:
>> I'm wondering if anyone knows of any sources of histories - formal or
>> anecdotal - for things like the introduction of source-code comments
>> in the early era of stored-program computers. I have some bits and
>> pieces, but I'm always looking for other interesting tidbits I could
>> throw in.
>>
> All the source code I've seen for EDSAC, back as early as 1949, has included
> comments. Whether they were written at the time, which seems likely, or
> added later I can't say.
> See: http://www.dcs.wawrwick.ac.uk/~edsac/ and look at the tutorial guide.
> Some other docs in the links section.
>
In card-time comments were essentially "free", using otherwise unused
space on a card. Early IBM assembler manuals recommended a comment on
every line.
Systems that stored programs on disk in variable-length files
discouraged comments, since they then too up valuable space on disk.
Unix represents perhaps the ultimate expression of this. Not only is C
"terse";-) much C code was, and some still is, written without comments.
Thos of us brought up with cards still comment heavily, but it seems
to be something programmers are just re-learning.
Robert Billing
> On Sat, 07 Feb 2009 17:15:54 -0500, Michael Wojcik <mwo...@newsguy.com> wrote:
>> I'm wondering if anyone knows of any sources of histories - formal or
>> anecdotal - for things like the introduction of source-code comments
>> in the early era of stored-program computers. I have some bits and
>> pieces, but I'm always looking for other interesting tidbits I could
>> throw in.
>>
> All the source code I've seen for EDSAC, back as early as 1949, has included
> comments. Whether they were written at the time, which seems likely, or
> added later I can't say.
> See: http://www.dcs.wawrwick.ac.uk/~edsac/ and look at the tutorial guide.
> Some other docs in the links section.
>
I think that's likely. When I was an undergrad in Cambridge in the 70's
some of the old EDSAC team were still lecturing, and they taught us to
comment heavily and clearly, a habit I still retain.
Morten Reistad
This has been kept, and refined. The current "standard" is
Doxygen, which acts as you describe. It does keep track of
some code rudiments, like procedure names, and it can integrate
with what you would call a -cref listing.
It also can do a project-wide crossref of symbols and documentation.
-- mrr
Joe Morris
Not directly answering your request, but here are a few things to think
about:
Don't forget to include in your presentation the old Real Programmers joke:
Real Programmers don't write comments. If it was hard to write it should be
hard to read.
Peter Flass responded to your note with a comment about programmers "just
re-learning" the concept of commenting. I question that description,
although I can't claim that it isn't happening. Or maybe my problem is that
my background is system programming at the assembler level, and my practice
is to use comments to provide a running commentary on the program logic.
I would *love* to see instructors fail a student program that didn't include
appropriate comments.
Humor. Programmers should remember that reading somebody else's code isn't
often seen as a recreational activity, and dropping in a bit of humor here
and there is a good idea, at least as long as it's likely to be recognized
as such. An example periodically cited here in a.f.c: the IBM VM module
DMKSTP which made the system run better. Another (which I've posted here in
the past) is the comment in the IHACVT macro for OS/360 MFT prior to release
21.7:
FINCH (FIND AND FETCH) WAS ALMOST RENAMED BLETCH
(BLDL AND FETCH) WHEN FIND WAS RENAMED BLDL
Sadly, the suits at IBM removed that comment in the final distribution.
Appropriate level of detail: Some programmers seem to believe that it's a
Good Idea to include utterly redundant comments, such as
LoadRegister 3,foo ;// Load foo into register 3
which does nothing but waste the reader's time. The only time that this
level of commentary might be useful would be where the harware documentation
is incorrect or incomplete, or where a particularly complex hack (original
meaning!) is being used. Two examples from my 709x/704x experiences:
* Memory protection instructions - documented *only* in the student guide
* consequences of indexing with more than one register - critical
information missing from the PoOp about writeback. (It took me 30 years and
a posting here in a.f.c to finally understand why a program I was assigned
to modify didn't work right...I could cheerfully murder the original
programmer.)
Joe Morris
Joe Pfeiffer
>
> Peter Flass responded to your note with a comment about programmers "just
> re-learning" the concept of commenting. I question that description,
> although I can't claim that it isn't happening. Or maybe my problem is that
> my background is system programming at the assembler level, and my practice
> is to use comments to provide a running commentary on the program logic.
This seems to be something every generation of programmers has had to
relearn; it isn't until we try to figure out what on earth we were
thinking when we wrote *that* that we realize our instructors weren't
just demanding comments as make-work.
> I would *love* to see instructors fail a student program that didn't include
> appropriate comments.
I don't know if I've ever taken it to that extreme, but I've sure
taken many points.
> Humor. Programmers should remember that reading somebody else's code isn't
> often seen as a recreational activity, and dropping in a bit of humor here
> and there is a good idea, at least as long as it's likely to be recognized
> as such. An example periodically cited here in a.f.c: the IBM VM module
> DMKSTP which made the system run better. Another (which I've posted here in
> the past) is the comment in the IHACVT macro for OS/360 MFT prior to release
> 21.7:
>
> FINCH (FIND AND FETCH) WAS ALMOST RENAMED BLETCH
> (BLDL AND FETCH) WHEN FIND WAS RENAMED BLDL
>
> Sadly, the suits at IBM removed that comment in the final distribution.
My all time favorite was a comment on an error message in the old
curses library: "we don't do that under Bozo's big top"
> Appropriate level of detail: Some programmers seem to believe that it's a
> Good Idea to include utterly redundant comments, such as
>
> LoadRegister 3,foo ;// Load foo into register 3
I've also taken points for comments like that.
Jeremy Nicoll - news posts
> See: http://www.dcs.wawrwick.ac.uk/~edsac/ and look at the tutorial guide.
> Some other docs in the links section.
URL should be: http://www.dcs.warwick.ac.uk/~edsac/
--
Jeremy C B Nicoll - my opinions are my own.
Email sent to my from-address will be deleted. Instead, please reply
to newsre...@wingsandbeaks.org.uk replacing "nnn" by "284".
Larry__Weiss
> In March, I'm going to give a short presentation at the annual
> conference of the Association of Teachers of Technical Writing about
> programming as technical writing. Since programmers often have to read
> source code, they're as much an audience for it as the compiler is,
> and so writing code can be seen as an exercise in technical writing.
> I'm wondering if anyone knows of any sources of histories - formal or
> anecdotal - for things like the introduction of source-code comments
> in the early era of stored-program computers. I have some bits and
> pieces, but I'm always looking for other interesting tidbits I could
> throw in.
>
The most striking use of comments I recall was the efforts to embed
diagrammatic constructions like data layouts into the source code.
Several years ago we had a discussion here of the topic of using simple
printable characters to create this sort of diagram.
http://groups.google.com/group/alt.folklore.computers/browse_thread/thread/2ab3a4cac6d48864/5ccc502f880edc8d?hl=en&lnk=gst&q=diagrams#5ccc502f880edc8d
or: http://tinyurl.com/bldaef
I wish I knew of actual source fragments that had that sort of embedded
diagram.
One reality of almost all source code is that the presentation font is
monospaced,
and that aids the consistent rendering of that sort of diagram immensely.
Here's a sample of what that might look like using C++ commenting and
simple
block diagramming characters:
//
// TCP Header Format
//
// 0 1 2 3
// 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | Source Port | Destination Port |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | Sequence Number |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | Acknowledgment Number |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | Data | |U|A|P|R|S|F| |
// | Offset| Reserved |R|C|S|S|Y|I| Window |
// | | |G|K|H|T|N|N| |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | Checksum | Urgent Pointer |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | Options | Padding |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
// | data |
// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
//
- Larry
Larry__Weiss
The most striking use of comments I recall was the efforts to embed
Anne & Lynn Wheeler
Larry__Weiss <l...@airmail.net> writes:
> The most striking use of comments I recall was the efforts to embed
> diagrammatic constructions like data layouts into the source code.
> Several years ago we had a discussion here of the topic of using simple
> printable characters to create this sort of diagram.
IBM (asembler) macro library DSECTS (storage definitions)) normally
always had storage layout diagrams (at least back thru 360 assembler
days) ... one of the other posts in the thread mentions this reference:
http://publibz.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/DSNAG0F5/1.2.3.1?SHELF=&DT=19990716185412
and some of my posts from that thread:
http://www.garlic.com/~lynn/2003k.html#42 text character based diagrams in technical documentation
http://www.garlic.com/~lynn/2003k.html#43 text character based diagrams in technical documentation
http://www.garlic.com/~lynn/2003k.html#44 text character based diagrams in technical documentation
http://www.garlic.com/~lynn/2003k.html#45 text character based diagrams in technical documentation
for instance, part of DSECT from (hercules) vm370 source ... mentioned
in this recent post
http://www.garlic.com/~lynn/2008s.html#64 Computer History Museum
.MIH01 ANOP
MIHREC DSECT
*
*** MISSING INTERRUPT HANDLER ERROR RECORD
*
* +---------+----+----+----+----+---------+
* | MIHKEYN | S1 | S2 | S3 | S4 | MIHSPE1 |
* +---------+----+----+----+----+---------+
* | MIHDTEN | MIHTMEN |
* +-------------------+-------------------+
* | MIHCPID |
* +---------------------------------------+
* | MIHJOB |
* +-------------+---------------+---------+
* | MIHCUA2 | MIHCUA1 | MIH - |
* +-------------------+-------------------+
* | VOL | MIHDEVT |
* +-------------------+-------------------+
* | MIHINT |
* +---------------------------------------+
--
40+yrs virtualization experience (since Jan68), online at home since Mar70
greymaus
> Michael Wojcik wrote:
> // | Data | |U|A|P|R|S|F| |
> // | Offset| Reserved |R|C|S|S|Y|I| Window |
> // | | |G|K|H|T|N|N| |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> // | Checksum | Urgent Pointer |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> // | Options | Padding |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> // | data |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> //
>
> - Larry
Oversnipped, sorry, anyway re: comments
Most common reason for not commenting was job retention, "Nobody will
understand it except me", (Forgetting that even if you were the
writer, a couple of even weeks, not years, later it is hard to
remember what was happening). Negated by the fact that
firers_and_hirers are usually ignorant of how obtuse code can be. I
remember instances where people have been brought back from
retirement to explain how something works, not even in computer code,
but general machinery. In one well-loved instance, the
easily-replacable person had died.
--
greymaus
.
.
...
Morten Reistad
greymaus <grey...@mail.com> wrote:
>On 2009-02-09, Larry__Weiss <l...@airmail.net> wrote:
>>
>> - Larry
>
>Oversnipped, sorry, anyway re: comments
>
>Most common reason for not commenting was job retention, "Nobody will
>understand it except me", (Forgetting that even if you were the
>writer, a couple of even weeks, not years, later it is hard to
>remember what was happening).
I once had to write an implementation of X.25, because the vendor
code was crashing, and no help was in sight. The project took three
weeks of coding, another week of commenting.
Every procedure had references to the standard, state diagrams
and lots of comments not only to what happend, but why. There were
more than 40 explicit references to litterature.
I wrote a 40-page document describing the principles of operations.
It is the best commented and documented thing I ever did. I even
built a separate componenet test bed for it.
Still noone dared touch the code. They didn't even dare COMPILE
the code, the used binary emulation when they moved it to a new
OS. I was called in from time to time to handle the applications
using it.
The same binary ran 11 years later when they finally decommishoned
X.25 support.
The problem was that the people taking over didn't understand the
theory. If you haven't got that base, you are USCWoaP. Several of
them had the exams, but they were only able to use pre-made
libraries, not actually maintain the driver code.
The average programmer has a profound fear to touch production
OS or driver code. Documentation does not help here. Linux and
BSD are some of the best analysed and documented code; still the
BSD network stack is almost untouched from the 4.2 BSD days, except
someone wrote IPv6 support. They regularly bungle TCP handling in
linux when they try to improve it.
How this is to be communicated to new people is a challenge.
>Negated by the fact that
>firers_and_hirers are usually ignorant of how obtuse code can be. I
>remember instances where people have been brought back from
>retirement to explain how something works, not even in computer code,
>but general machinery. In one well-loved instance, the
>easily-replacable person had died.
I invoice large amounts for such visits.
-- mrr
jmfbahciv
Yay! How are ya?
/BAH
jmfbahciv
However, if you have an instructor who insists on comments on every
line, that is exactly what I would write. Some lines simply don't
need a comment when the code says it all.
<snip>
/BAH
jmfbahciv
/BAH
Stan Barr
<jn.nntp....@wingsandbeaks.org.uk> wrote:
> Stan Barr <pla...@dsl.pipex.com> wrote:
>
>> See: http://www.dcs.wawrwick.ac.uk/~edsac/ and look at the tutorial guide.
>> Some other docs in the links section.
>
> URL should be: http://www.dcs.warwick.ac.uk/~edsac/
>
D@mn! I really must get the cut-and-paste working properly on this new
machine so I don't have to re-type! Gnome isn't as consistent as my old
X and Afterstep setup. One step forward, two steps back...
Larry__Weiss
> The average programmer has a profound fear to touch production
> OS or driver code. Documentation does not help here. Linux and
> BSD are some of the best analysed and documented code; still the
> BSD network stack is almost untouched from the 4.2 BSD days, except
> someone wrote IPv6 support. They regularly bungle TCP handling in
> linux when they try to improve it.
>
> How this is to be communicated to new people is a challenge.
>
I use the term "experienced code" for that code that hasn't been touched for
years, and is still in use.
As your example of IPv6 shows, it's usually an environmental change that
mandates eventual changes to the code. Sometimes it is a security concern that
does it (fixing a buffer overrun vulnerability, for example).
- Larry
Larry__Weiss
> That was very common in my early DEC years.
>
I just don't see it done anymore (creating diagrams in comment form inside
source code). It was particularly nice since it affixed the diagram with the
source. Today's utilities like Visio can certainly produce great looking
diagrams, but they aren't as well "glued" to the source code.
- Larry
Tim McCaffrey
Most of basics about the goodness of comments was drilled into me at
MSU, mostly via the Yourdon book at the time ("Structured
Programming"?), where he gives several anecdotes about how *not* to
comment a program.
- Tim
krw
You'd probably like one of my cow-orkers who used song lyrics for
comments.
krw
I still do it anytime I write code (either assembler or VHDL). I
usually expand any bits with descriptive names, either with the
whole name below it with arrows or a text bulleted list.
krw
<EMmdnWTBeu43sg3U...@posted.internetamerica>,
l...@airmail.net says...>
Timing diagrams too.
Larry__Weiss
> Most of basics about the goodness of comments was drilled into me at
> MSU, mostly via the Yourdon book at the time ("Structured
> Programming"?), where he gives several anecdotes about how *not* to
> comment a program.
>
The "problem" with comments is there is no guarantee over time that they will
get maintained as the source code changes. When examining source code I have
learned to have an attitude of distrust regarding comments in code that has a
lot of change history, especially a change history involving many coders.
- Larry
krw
grey...@mail.com says...>
> > Michael Wojcik wrote:
> > // | Data | |U|A|P|R|S|F| |
> > // | Offset| Reserved |R|C|S|S|Y|I| Window |
> > // | | |G|K|H|T|N|N| |
> > // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> > // | Checksum | Urgent Pointer |
> > // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> > // | Options | Padding |
> > // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> > // | data |
> > // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> > //
> >
> > - Larry
>
> Oversnipped, sorry, anyway re: comments
>
> Most common reason for not commenting was job retention, "Nobody will
> understand it except me", (Forgetting that even if you were the
> writer, a couple of even weeks, not years, later it is hard to
> remember what was happening).
That's why I do all my documentation in the code. I'll *never*
remember what I did even a month later. Separate files will be
separated and forget about keeping them in sync.
> Negated by the fact that
> firers_and_hirers are usually ignorant of how obtuse code can be. I
> remember instances where people have been brought back from
> retirement to explain how something works, not even in computer code,
> but general machinery. In one well-loved instance, the
> easily-replacable person had died.
Firers_and_hirers are usually ignorant about how much time it takes
to properly document code. Perhaps not so ignorant as it not being
a priority in *today's* battle.
krw
o1A3UnZ2dn...@posted.internetamerica>, l...@airmail.net
says...>
While that's certainly true, separate documents are even worse.
Are you arguing for no documentation?
Joe Pfeiffer
>>> Appropriate level of detail: Some programmers seem to believe that
>>> it's a Good Idea to include utterly redundant comments, such as
>>>
>>> LoadRegister 3,foo ;// Load foo into register 3
>>
>> I've also taken points for comments like that.
>
> However, if you have an instructor who insists on comments on every
> line, that is exactly what I would write. Some lines simply don't
> need a comment when the code says it all.
Well, if you demand a comment per line you're going to get what you
deserve. Though it is surprising just how many comments assembly code
takes compared to even C. In the example above, I could easily
imagine it to be part of a check like
LoadRegister 3,foo ; Make sure foo...
BranchEQ errhandler ; ...isn't a NULL pointer
Joe Pfeiffer
>
> You'd probably like one of my cow-orkers who used song lyrics for
> comments.
I once commented a timeout handler (that terminated the program when
it concluded it had gone rogue) with the lyrics to "Suicide is
Painless".
krw
Walter Bushell
> Oversnipped, sorry, anyway re: comments
>
> Most common reason for not commenting was job retention, "Nobody will
> understand it except me", (Forgetting that even if you were the
> writer, a couple of even weeks, not years, later it is hard to
> remember what was happening). Negated by the fact that
> firers_and_hirers are usually ignorant of how obtuse code can be. I
> remember instances where people have been brought back from
> retirement to explain how something works, not even in computer code,
> but general machinery. In one well-loved instance, the
> easily-replacable person had died.
>
The cemeteries hold lots of indispensable men.
Jorgen Grahn
> In article <gmmo9...@news1.newsguy.com>, jmfbahciv <jmfbahciv@aol> wrote:
...
>>One of Peter Conklin's grandiose ideas, which never ended up working
>>well, was to have the comments in MACRO-10 source code be "encoded"
>>with RUNOFF commands. He modified RUNOFF to ignore the code and
>>use the coments (minus the ;) as its input. What should have
>>been spit out was a foo.DOC (but that's the wrong extension I think)
>>which should have been the real documentation for each MACRO-10
>>source file.
>>
>>If you want to see an example, get the files SCAN.MAC and WILD.MAC.
>>Conklin wrote those while he was advocating this scheme of his.
>>
>>It would have been nice. All the technical writers would have had
>>to do, to produce a technical manual for New Bedford, would run
>>the source through RUNOFF. However, most of our programmers did
>>not have the typesetting style of thinking.
>
> This has been kept, and refined. The current "standard" is
> Doxygen, which acts as you describe.
And since it can generate Unix man pages, there is even a connection
via troff and roff back to RUNOFF (although you don't get to use troff
requests in your comments).
/Jorgen
--
// Jorgen Grahn <grahn@ Ph'nglui mglw'nafh Cthulhu
\X/ snipabacken.se> R'lyeh wgah'nagl fhtagn!
Jorgen Grahn
> "Joe Morris" <j.c.m...@verizon.net> writes:
>>
>> Peter Flass responded to your note with a comment about programmers "just
>> re-learning" the concept of commenting. I question that description,
>> although I can't claim that it isn't happening. Or maybe my problem is that
>> my background is system programming at the assembler level, and my practice
>> is to use comments to provide a running commentary on the program logic.
>
> This seems to be something every generation of programmers has had to
> relearn; it isn't until we try to figure out what on earth we were
> thinking when we wrote *that* that we realize our instructors weren't
> just demanding comments as make-work.
IME, you see all kinds:
- no comments (out of pure ignorance)
- no comments (believing that "the unit tests are the documentation")
- commenting as if it's assembly when it isn't (superfluous descriptions
for every other statement)
- mandated fixed-format headings according to template (but so dry that
noone bothers to read it, or update it as the code changes)
- comment only what the source code itself cannot express
And variations thereof. I prefer the last one.
>> I would *love* to see instructors fail a student program that didn't include
>> appropriate comments.
>
> I don't know if I've ever taken it to that extreme, but I've sure
> taken many points.
I went through some C listings of mine from ~1992 the other day, and
my instructor had some nasty things to say (scribble, in red) about my
indentation habits. And indeed, it was ugly.
>> Humor. Programmers should remember that reading somebody else's code isn't
>> often seen as a recreational activity, and dropping in a bit of humor here
>> and there is a good idea, at least as long as it's likely to be recognized
>> as such. An example periodically cited here in a.f.c: the IBM VM module
>> DMKSTP which made the system run better. Another (which I've posted here in
>> the past) is the comment in the IHACVT macro for OS/360 MFT prior to release
>> 21.7:
>>
>> FINCH (FIND AND FETCH) WAS ALMOST RENAMED BLETCH
>> (BLDL AND FETCH) WHEN FIND WAS RENAMED BLDL
>>
>> Sadly, the suits at IBM removed that comment in the final distribution.
>
> My all time favorite was a comment on an error message in the old
> curses library: "we don't do that under Bozo's big top"
I generally like humorous comments, but I hate them when it's obvious
that the author wasted time trying to look clever when he should have
explained what the code was doing -- or rewritten it to be clear, safe
and not broken.
I think humor can only be appreciated in good code.
Charlie Gibbs
k...@att.zzzzzzzzz (krw) writes:
> You'd probably like one of my cow-orkers who used song lyrics for
> comments.
I like that! Got any examples?
The bit of my code that I'm most proud of is a routine that
determines how many days are in a given month:
if ((month == 9) /* Thirty days hath September, */
|| (month == 4) /* April, */
|| (month == 6) /* June, */
|| (month == 11)) { /* and November. */
days = 30;
} else if (month != 2) { /* All the rest have thirty-one, */
days = 31;
} else { /* Except for February alone, */
if ((year % 4) != 0) {
days = 28; /* Which has but twenty-eight days clear, */
} else {
days = 29; /* And twenty-nine in each leap year. */
}
}
Okay, so it won't work in 2100 - but that's a one-line fix that
won't disturb the flow of the comments.
--
/~\ cgi...@kltpzyxm.invalid (Charlie Gibbs)
\ / I'm really at ac.dekanfrus if you read it the right way.
X Top-posted messages will probably be ignored. See RFC1855.
/ \ HTML will DEFINITELY be ignored. Join the ASCII ribbon campaign!
krw
cgi...@kltpzyxm.invalid says...>
> k...@att.zzzzzzzzz (krw) writes:
>
> > You'd probably like one of my cow-orkers who used song lyrics for
> > comments.
>
> I like that! Got any examples?
No. It was some time ago. He was memorable for being an excellent
programmer with extremely high productivity, but meaningless
comments when there were any. Good thing his stuff worked (...and
I'm a hardware type).
> The bit of my code that I'm most proud of is a routine that
> determines how many days are in a given month:
>
> if ((month == 9) /* Thirty days hath September, */
> || (month == 4) /* April, */
> || (month == 6) /* June, */
> || (month == 11)) { /* and November. */
> days = 30;
> } else if (month != 2) { /* All the rest have thirty-one, */
> days = 31;
> } else { /* Except for February alone, */
> if ((year % 4) != 0) {
> days = 28; /* Which has but twenty-eight days clear, */
> } else {
> days = 29; /* And twenty-nine in each leap year. */
> }
> }
>
> Okay, so it won't work in 2100 - but that's a one-line fix that
> won't disturb the flow of the comments.
...and break in 2000.
Joe Pfeiffer
>
> The bit of my code that I'm most proud of is a routine that
> determines how many days are in a given month:
>
> if ((month == 9) /* Thirty days hath September, */
> || (month == 4) /* April, */
> || (month == 6) /* June, */
> || (month == 11)) { /* and November. */
> days = 30;
> } else if (month != 2) { /* All the rest have thirty-one, */
> days = 31;
> } else { /* Except for February alone, */
> if ((year % 4) != 0) {
> days = 28; /* Which has but twenty-eight days clear, */
> } else {
> days = 29; /* And twenty-nine in each leap year. */
> }
> }
>
> Okay, so it won't work in 2100 - but that's a one-line fix that
> won't disturb the flow of the comments.
I like it! I suppose pointing out that you really ought to have an
enumerated type for the months instead of integers would sort of spoil
the fun....
Walter Bushell
"Charlie Gibbs" <cgi...@kltpzyxm.invalid> wrote:
> In article <MPG.23fa03714...@news.individual.net>,
> k...@att.zzzzzzzzz (krw) writes:
>
> > You'd probably like one of my cow-orkers who used song lyrics for
> > comments.
>
> I like that! Got any examples?
>
> The bit of my code that I'm most proud of is a routine that
> determines how many days are in a given month:
>
> if ((month == 9) /* Thirty days hath September, */
> || (month == 4) /* April, */
> || (month == 6) /* June, */
> || (month == 11)) { /* and November. */
> days = 30;
> } else if (month != 2) { /* All the rest have thirty-one, */
> days = 31;
> } else { /* Except for February alone, */
> if ((year % 4) != 0) {
> days = 28; /* Which has but twenty-eight days clear, */
> } else {
> days = 29; /* And twenty-nine in each leap year. */
> }
> }
>
> Okay, so it won't work in 2100 - but that's a one-line fix that
> won't disturb the flow of the comments.
We know what chaos about assuming the end of the century is far, far
away. In a way this is wurst, because your program may be running on an
emulation of an emulation of an emulation by then and x86 programs as
archaic as plug boards today. And if I'm not mistaken it will not work
for 2000 which still has to be handled in some applications.
Peter Flass
> // | Offset| Reserved |R|C|S|S|Y|I| Window |
> // | | |G|K|H|T|N|N| |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> // | Checksum | Urgent Pointer |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> // | Options | Padding |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> // | data |
> // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> //
>
> - Larry
>
>
You mean *everyone* doesn't do something like this when warranted?
Peter Flass
Bzzzt. 2000 was leap (if I've got it right yet.) It's years divisible
by 4 except years divisible by 100 except years divisible by 1000. Who
thought up this garbage anyway?
Charlie Gibbs
(Walter Bushell) writes:
You are mistaken. 2000 was a leap year, so my code kept chugging away
right through Y2K.
Charlie Gibbs
(Peter Flass) writes:
> krw wrote:
>
>> In article <1265.362T1...@kltpzyxm.invalid>,
>> cgi...@kltpzyxm.invalid says...>
>>
>>> Okay, so it won't work in 2100 - but that's a one-line fix that
>>> won't disturb the flow of the comments.
>>
>> ...and break in 2000.
>
> Bzzzt. 2000 was leap (if I've got it right yet.) It's years
> divisible by 4 except years divisible by 100 except years
> divisible by 1000.
400, actually.
> Who thought up this garbage anyway?
Some very clever people who realized that 365.25 days per year
wasn't accurate enough. (What's even more impressive was that
they had this figured out by 1582.)
Charlie Gibbs
grahn...@snipabacken.se (Jorgen Grahn) writes:
> IME, you see all kinds:
> - no comments (out of pure ignorance)
> - no comments (believing that "the unit tests are the documentation")
- no comments (believing that the code is so clearly written
that no comments are necessary (generally the mark of an
egotist - the fewer the comments, the more obfuscated
the code usually is)
- no comments (believing that the language is so self-documenting
that no comments are necessary (a common affliction of
Pascalites and Moduloids)
> - commenting as if it's assembly when it isn't (superfluous
> descriptions for every other statement)
...which can be just as superfluous in assembly language.
> - mandated fixed-format headings according to template (but so dry
> that noone bothers to read it, or update it as the code changes)
...typically taking the form of a 20-line block of comments
describing a 3-line subroutine - of which there are hundreds
(again, mandated by Structured Programming zealots who wormed
their way into management and don't have to write - much less
maintain - real code anymore)
> - comment only what the source code itself cannot express
> And variations thereof. I prefer the last one.
Me too. I add extra comments if I have to use an algorithm that
isn't immediately obvious, or which is so obscure that nobody
(sometimes even myself!) can understand it. Also included are
warnings about the dire consequences of messing with a seemingly
obvious routine that contains hidden gotchas that I've learned
from experience - like subtle interactions with other bits of code
that can't be factored out.
> I generally like humorous comments, but I hate them when it's obvious
> that the author wasted time trying to look clever when he should have
> explained what the code was doing -- or rewritten it to be clear, safe
> and not broken.
>
> I think humor can only be appreciated in good code.
Agreed. You have to earn the right to be humourous.
Joe Pfeiffer
>
> Bzzzt. 2000 was leap (if I've got it right yet.) It's years
> divisible by 4 except years divisible by 100 except years divisible by
> 1000. Who thought up this garbage anyway?
People who wanted to keep the seasons in the same place every year for
millenia into the future. It isn't like that formula is arbitrary,
you know.
Joe Morris
> jmfbahciv wrote:
[documentation flowcharts embedded in program source]
I've got a vague recollection that one of the IBM programs (Autoflow?) had
the ability to read a source deck in which comment statements could be
flagged as Autoflow commands; the idea (which I don't recall being used very
often) was that the programmer would embed comments describing the logical
flow of the program; Autoflow (or whatever) would then generate the
flowcharts using a 1403 as the "graphics" output device.
The concept was nice -- you get a toofer with program and logic in the same
deck. What I suspect happened in reality was that the program got updated
and the flowcharts didn't...
Joe Morris
Joe Morris
...and even worse than an obsolete comment is another consequence of lazy
programmers updating a source deck: breaking the "obvious" mnemonic meaning
of a symbol. IIRC it was the MFT-I nucleus assembly that one block of code
(the interrupt SLIH is sticking in my mind as the scene of the crime, or
maybe ABTERM) where you had symbolic register names (such as "R2") referring
to registers other than 2. Something along the line of
R2 EQU 4
My guess was (and still is) that this was caused by a change in an interface
elsewhere that forced a change in the nucleus code register usage, but
that's no excuse for using misleading mnemonics.
Joe Morris
Charles Richmond
Yes, and how many hundreds of years were heiroglyphics unreadable
because the folks who had the know-how had all expired????
--
+----------------------------------------------------------------+
| Charles and Francis Richmond richmond at plano dot net |
+----------------------------------------------------------------+
Charles Richmond
> In March, I'm going to give a short presentation at the annual
> conference of the Association of Teachers of Technical Writing about
> programming as technical writing. Since programmers often have to read
> source code, they're as much an audience for it as the compiler is,
> and so writing code can be seen as an exercise in technical writing.
>
> part of my talk will be about efforts to make code readable, from
> comments, to attempts at readable languages, to in-code documentation
> (Javadoc, Doxygen, etc), to Knuth's literate programming.
>
> I'm wondering if anyone knows of any sources of histories - formal or
> anecdotal - for things like the introduction of source-code comments
> in the early era of stored-program computers. I have some bits and
> pieces, but I'm always looking for other interesting tidbits I could
> throw in.
>
Here are a couple of things I have posted here before:
The following comment did *not* originate with me. It is for use
in front of an especially difficult code segment:
/****************************************************************
/-------------\
/ \
/ \
/ \
| XXXX XXXX |
| XXXX XXXX |
| XXX XXX |
\ X |
--\ XXX /--
| | XXX | |
| | | |
| I I I I I I I |
| I I I I I I |
\ /
-- --
\-------/
XXX XXX
XXXXX XXXXX
XXXXXXXXX XXXXXXXXX
XXXXX XXXXX
XXXXXXX
XXXXX XXXXX
XXXXXXXXX XXXXXXXXXX
XXXXX XXXXX
XXX XXX
**************
* BEWARE!! *
**************
All ye who enter here:
Most of the code in this module
is twisted beyond belief!
Tread carefully.
If you think you understand it,
You Don't,
So Look Again.
****************************************************************/
Another case of humorous comments was in a FORTRAN program that my
PPOE received from a competitor under a technology sharing agreement.
The comment came before a subroutine and went something like this:
************************************************************
* *
* I found this subroutine to be especially difficult to *
* understand, and you are going to find it difficult to *
* understand too... because I'm *not* going to tell you *
* how it works. *
* *
************************************************************
Walter Bushell
Peter Flass <Peter...@Yahoo.com> wrote:
>
> Bzzzt. 2000 was leap (if I've got it right yet.) It's years divisible
> by 4 except years divisible by 100 except years divisible by 1000. Who
> thought up this garbage anyway?
Best that could be done, since there is not an exact number of days in a
year. Calanders have gotten a *lot* of thought and this adding days to
February didn't cause problems before computers because the exceptions
to the every 4 years thing came around so seldom that exceptions were no
problem for manual systems.
Walter Bushell
"Charlie Gibbs" <cgi...@kltpzyxm.invalid> wrote:
> In article <gmqcse$7k9$1...@news.motzarella.org>, Peter...@Yahoo.com
> (Peter Flass) writes:
>
> > krw wrote:
> >
> >> In article <1265.362T1...@kltpzyxm.invalid>,
> >> cgi...@kltpzyxm.invalid says...>
> >>
> >>> Okay, so it won't work in 2100 - but that's a one-line fix that
> >>> won't disturb the flow of the comments.
> >>
> >> ...and break in 2000.
> >
> > Bzzzt. 2000 was leap (if I've got it right yet.) It's years
> > divisible by 4 except years divisible by 100 except years
> > divisible by 1000.
>
> 400, actually.
>
> > Who thought up this garbage anyway?
>
> Some very clever people who realized that 365.25 days per year
> wasn't accurate enough. (What's even more impressive was that
> they had this figured out by 1582.)
I suppose in the real old times they just added a few days every now and
again. Declare a holiday or something, "The normal 5 day holiday will be
extended to 6 days this year, enjoy!"
Rostyslaw J. Lewyckyj
For the month lengths you need to thank the Roman Caesars.
For the leap years, it's just Mother Nature:
You see, the year isn't exactly a whole number of days long.
So we have to make adjustments to keep the dates on the calendar
from wandering. See:
http://en.wikipedia.org/wiki/Year
http://www.infoplease.com/spot/leapyear2.
After 4 years you have accumulated an extra day and need to correct
the calendar by sticking that day somewhere. So bingo the leap year.
Then in one hundred years of this you would have over corrected
by a day and so you need to leave out a correction.
Similarly at the 400 year mark and at the 1000 year marks you need to
do more correcting.
--
Rostyk
Joe Pfeiffer
>
> I suppose in the real old times they just added a few days every now and
> again. Declare a holiday or something, "The normal 5 day holiday will be
> extended to 6 days this year, enjoy!"
Or not. When the Gregorian Calendar was adopted, a ten day correction
of accumulated errors in the Julian Calendar was corrected by moving
the date forward. I've read that some people interpreted this as ten
days having been stolen from their lives, and were upset.
kkt
I'm not sure when you mean by "real old times", but people stopped
adding days willy-nilly with Caesar's calendar reform in 45 BCE.
Since then there's been only one adjustment that required adding extra
days, the Gregorian reform, in 1582 in Catholic countries and various
later years in Protestant ones.
-- Patrick
Ahem A Rivet's Shot
Joe Pfeiffer <pfei...@cs.nmsu.edu> wrote:
> Or not. When the Gregorian Calendar was adopted, a ten day correction
> of accumulated errors in the Julian Calendar was corrected by moving
> the date forward. I've read that some people interpreted this as ten
> days having been stolen from their lives, and were upset.
Those days should be repaid - with interest.
--
Steve O'Hara-Smith | Directable Mirror Arrays
C:>WIN | A better way to focus the sun
The computer obeys and wins. | licences available see
You lose and Bill collects. | http://www.sohara.org/
Peter Flass
I like to put a "block comment" at the beginning of significant routines
(however I choose to define them) just to make them easier to find in
the code. I usually have several levels of block to indicate nesting,
for example (FWIW):
(read with fixed-pitch font)
%page;
/************* <... to col 60, or 80 maybe ..>*****/
/* major: This routine does blah-blah */
/**************************************************/
/*------------------------------------------------*/
/* lesser: blah blah */
/*------------------------------------------------*/
/*--- ... maybe to col 40 ... ---*/
/* still lesser... */
/*-------------------------------*/
Peter Flass
Before editors it was a lot more error-prone to make a global change ike
R3==>R2. OTOH, I agree with you.
Peter Flass
That makes the most sense to me. 360-day years with a 5- or 6-day
intercalary holiday.
jmfbahciv
the reason that Conklin's plan didn't work.
/BAH
jmfbahciv
> In article <gmp6r...@news5.newsguy.com>, jmfbahciv@aol says...>
>>> "Joe Morris" <j.c.m...@verizon.net> writes:
>>>> Peter Flass responded to your note with a comment about programmers "just
>>>> re-learning" the concept of commenting. I question that description,
>>>> although I can't claim that it isn't happening. Or maybe my problem is that
>>>> my background is system programming at the assembler level, and my practice
>>>> is to use comments to provide a running commentary on the program logic.
>>> This seems to be something every generation of programmers has had to
>>> relearn; it isn't until we try to figure out what on earth we were
>>> thinking when we wrote *that* that we realize our instructors weren't
>>> just demanding comments as make-work.
>>>
>>>> appropriate comments.
>>> I don't know if I've ever taken it to that extreme, but I've sure
>>> taken many points.
>>>
>>>> often seen as a recreational activity, and dropping in a bit of humor here
>>>> and there is a good idea, at least as long as it's likely to be recognized
>>>> as such. An example periodically cited here in a.f.c: the IBM VM module
>>>> DMKSTP which made the system run better. Another (which I've posted here in
>>>> the past) is the comment in the IHACVT macro for OS/360 MFT prior to release
>>>> 21.7:
>>>>
>>>> FINCH (FIND AND FETCH) WAS ALMOST RENAMED BLETCH
>>>> (BLDL AND FETCH) WHEN FIND WAS RENAMED BLDL
>>>>
>>>> Sadly, the suits at IBM removed that comment in the final distribution.
>>> My all time favorite was a comment on an error message in the old
>>> curses library: "we don't do that under Bozo's big top"
>>>
>>>> Good Idea to include utterly redundant comments, such as
>>>>
>>>> LoadRegister 3,foo ;// Load foo into register 3
>>> I've also taken points for comments like that.
>> However, if you have an instructor who insists on comments on every
>> line, that is exactly what I would write. Some lines simply don't
>> need a comment when the code says it all.
>
> You'd probably like one of my cow-orkers who used song lyrics for
> comments.
TW's style was to write, then debug his code. Then he would be forced
to comment it. Since he always forgot what he did yesterday, you
could find a couple of comments (he had a TECO macro which would
present the line of code and input put his typing as a comment, then
output it to the source) which said, "Beats the shit outta me".
Some supervisor (I can't recall which one but could make a guess) had
a writer go through TW's sources and delete those.
/BAH
jmfbahciv
> jmfbahciv <jmfbahciv@aol> writes:
>
>>>> Appropriate level of detail: Some programmers seem to believe that
>>>> it's a Good Idea to include utterly redundant comments, such as
>>>>
>>>> LoadRegister 3,foo ;// Load foo into register 3
>>> I've also taken points for comments like that.
>> However, if you have an instructor who insists on comments on every
>> line, that is exactly what I would write. Some lines simply don't
>> need a comment when the code says it all.
>
> deserve. Though it is surprising just how many comments assembly code
> takes compared to even C. In the example above, I could easily
> imagine it to be part of a check like
>
> LoadRegister 3,foo ; Make sure foo...
> BranchEQ errhandler ; ...isn't a NULL pointer
that's a useful comment. What I'm talking about is a subroutine
which ends in a POPJ P, It certainly doesn't need a ;Return to caller
comment in it. And this kind of junk wasted bits on the magtapes when
shipped. Every little bit helped.
/BAH
jmfbahciv
Astronomy.
/BAH
jmfbahciv
If you look at old, before-typeset, DEC documentation, you might notice
that somebody drew lines over the +, -. Since we didn't have _ those
ended up being an extra line of dashes. I also don't remember using
the | character. That came later.
/BAH
jmfbahciv
> Tim McCaffrey wrote:
>> Most of basics about the goodness of comments was drilled into me at
>> MSU, mostly via the Yourdon book at the time ("Structured
>> Programming"?), where he gives several anecdotes about how *not* to
>> comment a program.
>>
>
> The "problem" with comments is there is no guarantee over time that they
> will get maintained as the source code changes. When examining source
> code I have learned to have an attitude of distrust regarding comments
> in code that has a lot of change history, especially a change history
> involving many coders.
But that is very useful, too. It gives you a hint about the original
intent. Sometimes, that has been deleted from all anals of history.
/BAH
jmfbahciv
it's a fucking PITA to type.
/BAH
jmfbahciv
We had a standard for this kind of stuff. Tape Prep did most
of the typing. I think Conklin also had set up a subroutine
template. I won't be able to say more about this kind of stuff
until I go through my boxes.
/BAH
Hans-Christian Becker
>But that is very useful, too. It gives you a hint about the original
>intent. Sometimes, that has been deleted from all anals of history.
^^^^^
Freudian slip?
--
Dr. Hans-Christian Becker
'96 VN750 SM5TLH KG6POK
Uppsala, Sweden
krw
Peter...@Yahoo.com says...>
Bzzzt, yourself. ;-)
If you make an exception for 2100 you also have to make another for
2000 to except the exception.
> It's years divisible
> by 4 except years divisible by 100 except years divisible by 1000. Who
^400
> thought up this garbage anyway?
Yes, the 400 exception to the 100 exception.
krw
pr...@panix.com says...>
Think about what that would do to accounting.
"Hey, I have to pay the mortgage again? ...but I've only received
three weeks pay!"
"Hey, I've got to pay joe again? ...he's only worked two days this
week!"
krw
cgi...@kltpzyxm.invalid says...>
> In article <proto-AAA09F....@news.panix.com>, pr...@panix.com
> (Walter Bushell) writes:
>
> > In article <1265.362T1...@kltpzyxm.invalid>,
> > "Charlie Gibbs" <cgi...@kltpzyxm.invalid> wrote:
> >
> >> Okay, so it won't work in 2100 - but that's a one-line fix that
> >> won't disturb the flow of the comments.
> >
> > away. In a way this is wurst, because your program may be running on
> > an emulation of an emulation of an emulation by then and x86 programs
> > as archaic as plug boards today. And if I'm not mistaken it will not
> > work for 2000 which still has to be handled in some applications.
>
> You are mistaken. 2000 was a leap year, so my code kept chugging away
> right through Y2K.
So did mine. I had to certify stuff I'd written in an earlier job
to be Y2K enabled. The hardest part was convincing the counters of
beans that my code had no concept of time. It never even saw a
clock. ;-)
Walter Bushell
Joe Pfeiffer <pfei...@cs.nmsu.edu> wrote:
We'll arrange it so the corrections move the date backwards, thereby
extending peoples lives.
krw
Macro, with that documented (a lot better than IEFBR14).
krw
Peter...@Yahoo.com says...>
That's exactly how I write VHDL block comments (well, with '--' in
front). I do a similar thing for inline comments where I use the
'*' block to set off the begin of a "case" (or "if"/"elsif" block)
and the '-' for each "when" (or "else").
krw
Walter Bushell
Charles Richmond <fri...@tx.rr.com> wrote:
> Walter Bushell wrote:
> > In article <slrngovtm9.l...@maushome.org>,
> > greymaus <grey...@mail.com> wrote:
> >
> >> Oversnipped, sorry, anyway re: comments
> >>
> >> Most common reason for not commenting was job retention, "Nobody will
> >> understand it except me", (Forgetting that even if you were the
> >> writer, a couple of even weeks, not years, later it is hard to
> >> remember what was happening). Negated by the fact that
> >> firers_and_hirers are usually ignorant of how obtuse code can be. I
> >> remember instances where people have been brought back from
> >> retirement to explain how something works, not even in computer code,
> >> but general machinery. In one well-loved instance, the
> >> easily-replacable person had died.
> >>
> >
> > The cemeteries hold lots of indispensable men.
> >
>
> Yes, and how many hundreds of years were heiroglyphics unreadable
> because the folks who had the know-how had all expired????
Exactly, sometimes the man really *is* indispensable and the country
fails or the business goes belly up. OTOH, by the time hieroglyphics
were unreadable, was beyond the point were it was necessary read them.
Rostyslaw J. Lewyckyj
I wonder how mundane things like birthdays , or anniversaries,
or deadlines that fell on these adjusted days got resolved?
Eg. Would a full years interest be charged/given for the short
year? What if you were to be executed on a certain day and that
day was skipped on the calendar?
Or if it was not? Would they allow you the lost days to live?
--
Rostyk
Rostyslaw J. Lewyckyj
>
> Do you have a reference for the 1000-year correction? (Or did you mean
> 100-year mark?)
>
> Louis
Neither! I simply goofed parroting what was in a previous article.
John Everett
>Michael Wojcik wrote:
>> In March, I'm going to give a short presentation at the annual
>> conference of the Association of Teachers of Technical Writing about
>> programming as technical writing. Since programmers often have to read
>> source code, they're as much an audience for it as the compiler is,
>> and so writing code can be seen as an exercise in technical writing.
>>
>> Of course many people have noticed this and responded to it, and so
>> part of my talk will be about efforts to make code readable, from
>> comments, to attempts at readable languages, to in-code documentation
>> (Javadoc, Doxygen, etc), to Knuth's literate programming.
>>
>> I'm wondering if anyone knows of any sources of histories - formal or
>> anecdotal - for things like the introduction of source-code comments
>> in the early era of stored-program computers. I have some bits and
>> pieces, but I'm always looking for other interesting tidbits I could
>> throw in.
>>
>
>One of Peter Conklin's grandiose ideas, which never ended up working
>well, was to have the comments in MACRO-10 source code be "encoded"
>with RUNOFF commands. He modified RUNOFF to ignore the code and
>use the coments (minus the ;) as its input. What should have
>been spit out was a foo.DOC (but that's the wrong extension I think)
>which should have been the real documentation for each MACRO-10
>source file.
>
>If you want to see an example, get the files SCAN.MAC and WILD.MAC.
>Conklin wrote those while he was advocating this scheme of his.
>
>It would have been nice. All the technical writers would have had
>to do, to produce a technical manual for New Bedford, would run
>the source through RUNOFF. However, most of our programmers did
>not have the typesetting style of thinking.
>
>/BAH
Predating PFC's efforts, as part of the rationalization of the PDP-10
Monitor's sources during the development of the 5-Series release
(which contained the "Level-D" disk service), Tom Hastngs produced a
coding and commenting specification called LEVELD.MEM.
I just now did a Google search and found a .pdf version of the Five
Series Monitor Installation Guide, who's Table of Contents lists
LEVELD.MEM. Unfortunately the 289 page document is truncated before
one gets to LEVELD.MEM.
I believe LEVELD.MEM is an important document in the history of
commenting conventions which may now be lost. I'm wondering if anyone
might still have a copy.
--
jeverett3<AT>sbcglobal<DOT>net (John V. Everett)
Anne & Lynn Wheeler
jmfbahciv <jmfbahciv@aol> writes:
> ISTR keypunching a lot of cards that looked like that.
>
> If you look at old, before-typeset, DEC documentation, you might notice
> that somebody drew lines over the +, -. Since we didn't have _ those
> ended up being an extra line of dashes. I also don't remember using
> the | character. That came later.
360/370 principles of operation went thru typeset (early on) ... then
when it had been converted to cms script ... with principles of
operation a subset of the information in the "redbook" (for color of
3ring binder) architecture manual (cms script command line operation
resulted in the whole manual being printed or the principles of
operation subset) ... the boxes are drawn with +, -, | ... from
characters on 1403 printer. Then when got direct cms script ouput to
device that could draw boxes with solid lines ... it went back to
looking like the earlier typeset.
cms script was done in the mid 60s ... part of (virtual machine)
cp67/cms at the science center
http://www.garlic.com/~lynn/subtopic.html#545tech
... somewhat morph of the earlier ctss runoff command (ctss ran on
7094). then in 1969, gml was invented at the science center (by "G",
"M", & "L") ... and gml tag processing was added to script command, in
addition to runoff dot (".") processing. later in the 70s, gml was
standardized as sgml ...
http://www.garlic.com/~lynn/submain.html#sgml
a decade after that, sgml morphed into html (at cern) ... recent
discussion:
http://www.garlic.com/~lynn/2008p.html#67 Web Security hasn't moved since 1995
above has reference to the 1st web server outside europe/cern was on the
slac (virtual machine) vm370 (morph of cp67)
--
40+yrs virtualization experience (since Jan68), online at home since Mar70
krw
urj...@bellsouth.net says...>
> > Walter Bushell <pr...@panix.com> writes:
> >> I suppose in the real old times they just added a few days every now and
> >> again. Declare a holiday or something, "The normal 5 day holiday will be
> >> extended to 6 days this year, enjoy!"
> >
> > Or not. When the Gregorian Calendar was adopted, a ten day correction
> > of accumulated errors in the Julian Calendar was corrected by moving
> > the date forward. I've read that some people interpreted this as ten
> > days having been stolen from their lives, and were upset.
>
> I wonder how mundane things like birthdays , or anniversaries,
> or deadlines that fell on these adjusted days got resolved?
The same way they're resolved if they fall on Feb 29th. Define
Feb 29 == Mar 1.
> Eg. Would a full years interest be charged/given for the short
> year?
It is for a short month. Of course that was all worked out in the
contract.
> What if you were to be executed on a certain day and that
> day was skipped on the calendar?
You get to live a few days "longer". ;-)
> Or if it was not? Would they allow you the lost days to live?
Of course not. That would take an act of Congress.
Walter Bushell
"Rostyslaw J. Lewyckyj" <urj...@bellsouth.net> wrote:
> I wonder how mundane things like birthdays , or anniversaries,
> or deadlines that fell on these adjusted days got resolved?
> Eg. Would a full years interest be charged/given for the short
> year? What if you were to be executed on a certain day and that
> day was skipped on the calendar?
> Or if it was not? Would they allow you the lost days to live?
> --
> Rostyk
One could reference the historical pattern.
Joe Pfeiffer
>>
> But do programmers keep the comments in typesetable format? That was
> the reason that Conklin's plan didn't work.
No, but doxygen does a pretty good job of typesetting them anyway.
Comments that've been written to be "doxygen friendly" comes out
better, but it does better than you'd expect when they aren't.
Joe Pfeiffer
That was my point -- the previous comment example (which I quoted) is
like your POPJ P example: totally useless. But it's surpring how
densely commented assembly can be, and have those comments still be
useful.
greymaus
> In article <proto-7B0BA6....@news.panix.com>,
> pr...@panix.com says...>
>
>
> "Hey, I have to pay the mortgage again? ...but I've only received
> three weeks pay!"
>
> "Hey, I've got to pay joe again? ...he's only worked two days this
> week!"
>
series (7?) when all debts were negated. Biblical. Middle Ages, there
were limits on periods of debts, at which point the debt was written
off. Easy system for Barons in the period when most 'consumer' debt was
from Jews. [Hey, were Fuggers jewish?]. Again, there were limits on
land being taken over for bad debts, in Poland at least, and probably
in the case of Jewish moneylenders. (Something about this being a
problem in the early days of the Zionists, as they had little
experience of land management when they went to Palestine, there was
an experiment in buying land in Poland, to train future
bibbutz[ers?]). This has been noted in some of the accounts of the
Nakba, large areas of ex-Arab land were planted with European
evergreens, unsuited for arid areas
Semi-compulsory loans to soverigns were in constant danger of being
forgotten.
I believe that long-term loans (mortgages?) in common usage came in
during Roosvelts time?.
In my time, there were `Quarter days` and other significent times for
debts. Some unchanged from pre-Gregorian times, mid-May (Old may day)
being a significent one. This would be interpersonal deals. A lot of
land rentings started around March 1st ( a convenient time, start of
grass growth ), which was old New Year.
I remember my first time entering a bank.
--
greymaus
.
.
...
kkt
This website:
http://www.thehistoryof.net/history-of-home-mortgages.html
claims that from the early 1900s to 1929, typical mortgage terms were
50% down and 5 year loans, so relatively few people could get them.
But those who did would never be upside down and would own the
property outright in relatively short time. Then at the beginning of
the depression there was no money for anybody to get mortgages, and in
1934 the Federal Housing Administration was created and the 30-year
loan was born.
-- Patrick
Larry__Weiss
> ... my code had no concept of time.
>
What an interesting statement! I think I'll make that a design goal, that is,
to come as close to that as possible in any code I design to make it unaware of
time.
Sort of reminds me of the "Go To Statement Considered Harmful" idea.
- Larry
krw
5ZL3wYQzUnZ2...@posted.internetamerica>, l...@airmail.net
says...>
> > ... my code had no concept of time.
> >
>
> What an interesting statement!
What, you've never written timeless code?
> I think I'll make that a design goal, that is,
> to come as close to that as possible in any code I design to make it unaware of
> time.
Not a clock in sight (embedded micro in the user interface - no
blinkin' 12:00 allowed by design). /BAH would be a happy camper.
> Sort of reminds me of the "Go To Statement Considered Harmful" idea.
GOTOs don't do any harm and they're easy to test. It's the
conditionals that'll get you into trouble every time! ;-)
Error checking is easy. It's doing something useful when the
unexpected happens that's hard.
bbreynolds
wrote:
A good example of the handling of the shift in calendar dates
is George Washington's birth date. At the that he was born,
the split between the Julian calendar and the Gregorian calendar
was eleven days. As the British empire was still using April 1st
at the New Year's day, Washington was born on February 11, 1731.
After the jump of eleven days in September 1752, his birth date
may have been recorded as either February 11, 1731/1732 (O.S.)
or February 22, 1732. As Washington's mother refused to cook
two cherry pies in one year (let alone that cherries would not have
been available in February, except as preserves, and we know
what preserved cherries taste like when made into a pie), the
February 22nd date became the established date of President
Washington's birthday.
(O.S. = Old Style; dates in British publications from the
1752 split well into the mid-19th century relected the
calendar change by appending the "O.S." to prior dates).
And just to throw a monkey wrench into /BAH's desire to keep
all subjects under one header, I should mention that a few days
ago, on one of the yahoo railroad groups a poster did a pointer
to an image library, where the date of the image was shown as
January 01, 1753. Ah, says I, his software is using the epoch
date of the British ephemeris and nautical tables, as the first
New Year's day following the shift from the Julian to the Gregorian
calendar in the British Empire (I have never been able to pin
down exactly why the British Empire shifted on September 11th
to September 22nd in 1752, except to match up with that
year's autumnal equinox). Again, recall that this was the
first New Year's day on January 1st, rather than April 1st.
And it doth appear that SQL Server does use January 1, 1753
as its epoch date. Following through on some searches, this
date does seem to have well-supported the applications
written in SQL and MySQL, but some persons have
complained about ground rent contracts dated from 1704
getting befouled in the database, not only in having a "negative"
date, but not having accounting for that 11-day jump in 1752.
We of a.f.c. love to mention epoch dates, particularly during the
supposed post-Y2K period, where the runout of the Unix epoch
from January 1, 1970 expires in 2038.
One reference in the SQL discussion of 1753-01-01 says
that the epoch of Windows is 1601-01-01: I have never seen
anything to support that, particularly in that Windows has
problems with last Thursday. Any answers for the SQL
date or the Windows date?
I believe SAS is based on 1950-01-01: in that the original
emphasis of SAS was to be a counter-foil to the UC BioMeds
and SPSS, the 1950-01-01 epoch considered that half of the
prospective data point persons in a SAS experimental
population would have been born before that date, and
half-after. I do recall that SAS did have some date restrictions
which may have been removed in versions more recent than
those on which I have last worked.
The IBM 1130 and 1800 believed dates to based on
1960-01-01, and good for sixteen years. In 1976, a
one-word patch was supplied, at least for the 1800,
to move that base year to 1976: a few sites on which
I was working needed to have the patch update to a
base year of 1992, and at least two still-running
1800s with major systems supported should have it
boosted to 2008.
For my own work on the IBM Series/1 in EDX I have
used an EDX rewrite of the ACM Julian date (not
calendar, different Julian) algorithm to input the
NBS date/time clock and convert to day-of-week,
very much needed in the types of applications
which I support: the epoch date is January 1, 4713 BC/BCE.
and is good until 3726 AD/CE.
What other epoch dates are still hovering about?
Bruce B. Reynolds, Trailing Edge Technologies, Glenside PA
Rich Alderson
> On Feb 10, 9:25=EF=BF=BDam, "Rostyslaw J. Lewyckyj" <urj...@bellsouth.net>
> wrote:
[ nothing unsnipped ]
>> Joe Pfeiffer wrote:
>>> Walter Bushell <pr...@panix.com> writes:
>>>> I suppose in the real old times they just added a few days every now and
>>>> again. Declare a holiday or something, "The normal 5 day holiday will be
>>>> extended to 6 days this year, enjoy!"
That's exactly what the Romans did. Every few years, the Pontifex Maximus
(chief priest of the state religion) was supposed to take note of the drift of
the calendar and declare one or two intercalary days to move the seasons back
into agreement with the calendar.
Gaius Julius Caesar great innovation was the 4-year cycle of leap years. In
compensation, he renamed the month of Quinctilis after himself, and took a day
from Februarius so that the new Julius would be a long month.
(His greatnephew successor and heir liked that idea, so renamed Sextilis and
added a day to it at Februarius' expense as well.)
>>> Or not. When the Gregorian Calendar was adopted, a ten day correction of
>>> accumulated errors in the Julian Calendar was corrected by moving the date
>>> forward. I've read that some people interpreted this as ten days having
>>> been stolen from their lives, and were upset.
Yeah, that's the "not all centuries should be leap years" correction.
[ snip ]
> A good example of the handling of the shift in calendar dates
> is George Washington's birth date. At the that he was born,
> the split between the Julian calendar and the Gregorian calendar
> was eleven days. As the British empire was still using April 1st
^^^^^^^^^
> at the New Year's day, Washington was born on February 11, 1731.
> After the jump of eleven days in September 1752, his birth date
> may have been recorded as either February 11, 1731/1732 (O.S.)
> or February 22, 1732. As Washington's mother refused to cook
> two cherry pies in one year (let alone that cherries would not have
> been available in February, except as preserves, and we know
> what preserved cherries taste like when made into a pie), the
> February 22nd date became the established date of President
> Washington's birthday.
March 25. Read Boswell's biography of Johnson, for example.
--
Rich Alderson "You get what anybody gets. You get a lifetime."
ne...@alderson.users.panix.com --Death, of the Endless
Walter Bushell
Larry__Weiss <l...@airmail.net> wrote:
Next best is to let the system take care of dates and date arithmetic.
Walter Bushell
krw <k...@att.zzzzzzzzz> wrote:
It's the computed COME FROMs that cause the problems for me.
kkt
I don't know about Windows, but wikipedia says Jan. 1, 1601, is the
epoch for ANSI Cobol dates.
> I believe SAS is based on 1950-01-01: in that the original emphasis
> of SAS was to be a counter-foil to the UC BioMeds and SPSS, the
> 1950-01-01 epoch considered that half of the prospective data point
> persons in a SAS experimental population would have been born before
> that date, and half-after. I do recall that SAS did have some date
> restrictions which may have been removed in versions more recent
> than those on which I have last worked.
> The IBM 1130 and 1800 believed dates to based on 1960-01-01, and
> good for sixteen years. In 1976, a one-word patch was supplied, at
> least for the 1800, to move that base year to 1976: a few sites on
> which I was working needed to have the patch update to a base year
> of 1992, and at least two still-running 1800s with major systems
> supported should have it boosted to 2008.
> For my own work on the IBM Series/1 in EDX I have used an EDX
> rewrite of the ACM Julian date (not calendar, different Julian)
> algorithm to input the NBS date/time clock and convert to
> day-of-week, very much needed in the types of applications which I
> support: the epoch date is January 1, 4713 BC/BCE. and is good
> until 3726 AD/CE.
> What other epoch dates are still hovering about?
TOPS-10, TOPS-20, and VMS use Nov. 17, 1858. That date is the
base of the modified Julian Day Number.
-- Patrick
jmfbahciv
also in the specs section of the Notebooks before a certain writer
had all that stuff deleted from them? This deletion happened in the
early 80s, IIRC.
/BAH
/BAH
jmfbahciv
Somebody was a pretty good coder.
/BAH
jmfbahciv
[awed emoticon here] A male that didn't have to put a clock in
everything?
/BAH
jmfbahciv
Perhaps people's birthdays were counted like horses' are.
/BAH
jmfbahciv
Some days, it is useful to have the wrong date-time set.
/BAH
jmfbahciv
> In article <gmrti...@news2.newsguy.com>, jmfbahciv <jmfbahciv@aol> wrote:
>
>> But that is very useful, too. It gives you a hint about the original
>> intent. Sometimes, that has been deleted from all anals of history.
> ^^^^^
> Freudian slip?
>
<snort> I guess my fingers are smarter than I am.
/BAH
jmfbahciv
In my day, that was a human who did that by hand, uphill, both ways.
/BAH