Re: [Axiom-developer] Heidegger, literate programming, and communication

[Tim Daly]

>PS I have many chunks of code that I wrote 20-30 years ago and I have no
>idea why and what the code was written for!!!! even after reading each
>line of the code!!!!

This is what got me interested in literate programming. 

Axiom was written at IBM as "research code", mostly by people trying to
get a PhD. I wrote bits and pieces of the internals but didn't bother
to document anything, especially since I write "dirt simple code".

Fifteen years later I'm looking at my own code. I know what it does.
I can even tell you what bytes the compiler will lay down in memory.
I know the code is needed since the system fails if I remove it.

But I have no clue WHY I wrote it.

The person who wrote the code failed to communicate with the person
who maintains the code. I have the misfortune of being both people.

I understand the strong opposition to writing good documentation at any
level.  Especially when writing code; it just seems wasteful to "state
the obvious". 

One non-obvious side effect of doing literate programming is that the
code quality improves a LOT. As Bill Hart said:

    Another thing I've been enjoying lately is literate programming.
    Amazingly it turns out to be faster to write a literate program
    than an ordinary program because debugging takes almost no time.

I fear that we're going to have the same approach as the physicists.
"New theories get accepted when the previous generation dies out."

Fortunately statistics show that programmers retire into management
at age 35 so we won't have to wait that long. If there is any justice,
the managers will have to hire noobs to maintain code they wrote so
they get to listen to the noobs trash talk about their code. :-)

Tim Daly