On 10/1/2015 8:15 PM, Uncle Monster wrote:
On Thursday, October 1, 2015 at 10:02:16 PM UTC-5, Don Y wrote:
On 10/1/2015 7:28 PM, Uncle Monster wrote:

I live in fear of "forced" retirement -- i.e., when my mind or body can no
longer keep up with the goals that I set for myself. My current project
has me taxed to the limits of my abilities -- so much so that, for the
first time in my career, I actually wonder if I can pull it off!

I have no idea what to do *after* this as I'm sure whatever goal I set
*would* be unattainable! :

You can always do what extremely intelligent and creative people have done
since the beginning, take on an apprentice and pass on your knowledge to
someone younger. I've known a lot of guys who's sons weren't interested in
their profession so they had to find a young person who who was fascinated
with what they did and eager to learn. ^_^

But that inherently limits what *I* can learn (other than "how to teach").

I currently prepare "documents" that describe my thought processes for
each aspect of this project in a narrative fashion. So, *they* can
talk to those who follow after me: "Why did he choose to do THIS
instead of THAT? Ahhh... I see!"

It's also a force multiplier: it can talk to N people instead of me
having to answer the same (potentially) question N times from those
N people "in person".

I suppose that would make you a virtual instructor? ^_^

When writing code, you are encouraged to document what you have done
so those who "come after" can understand what the code is *trying* to do.

Too often, the "commentary" that folks include is ineffective.
For example, the statement:
count++;
means "add one to count". It is not uncommon to see the following
in someone's code:
count++; // add one
D'uh!

The other problem with "commentary" is that it becomes something that
others must "maintain" -- in addition to the code that it documents.

So, the more you write, the more another person will have to
rewrite/modify to reflect any changes that he/she imparts to your code.
Folks being lazy, what ends up happening is the commentary does NOT
get updated. So, the NEXT guy (after the guy who follows you)
scratches his head wondering why the commentary doesn't "make sense".

The alternative is the guy who follows you decides to just REMOVE your
commentary because he doesn't want to bother updating it.

By pulling the bulk of this information *out* of the program and
putting it in a separate document, there is less of a direct tie
to particular program statements (e.g., "count++"). So, less
need to maintain that level of commentary detail.

Instead, you (I) can concentrate on The Big Picture without getting
bogged down in all the trivial details of "implementation".

For example, I have a tiny speech synthesizer that I use in my
current project. Sufficeit to say, there is a LOT of technology
that goes into the algorithms. Trying to explain all of that
*in*/alongside the actual code would add 100 pages or "text"
to the code. And, be confined to *just* text!

By moving the documentation out of the "code", I can add illustrations,
animations and even sound samples to make what would be difficult or
ambiguous to explain in prose far more explicit. And, spare the
future developer/maintainer the effort of having to keep this up
to date to reflect the minutiae of each little change he opts to
impart to my codebase.

As it takes none of my time WHEN IT IS BEING EXAMINED/"read", the
documents can be consumed at leisure.