Techniques to document code?

[f***@gmail.com]

It's acknowledge by many that dating from its origins some decades ago:
single author Slackware had a unique/superior documentation method.
That's why several single-author systems have used it as their basis.
It's very frustrating when I can't understand the simplest little script
that I wrote a few days ago.
I suspect/hope there's a few fundamental rules to solve this problem.
And definitely NOT practice-makes-perfect.
IMO there's 2 ways of solving a problem: by association, like a football-player
or my dog, or a M$pook user, and then there's deduction: eg. where the
MINIMALIST underlying principals, like mass, length, time solve Newtonian
physics questions; or bits, bytes, files, directories in the unix family
consistently structure the solutions.
There's some good documentation by the unix originators, who went on to
refine it towards plan9...inferno...but I can't find any methods to capture-the-
underlying-logic of my own scripts, for later understanding/editing.
It reminds me of the undisciplined hacking of BASIC, before the days of
*STRUCTURED* programming. Where can I find documentation on this problem?

[Poprocks]

Post by f***@gmail.com
single author Slackware had a unique/superior documentation method.
That's why several single-author systems have used it as their basis.
It's very frustrating when I can't understand the simplest little script
that I wrote a few days ago.

[...]

Post by f***@gmail.com
There's some good documentation by the unix originators, who went on to
refine it towards plan9...inferno...but I can't find any methods to
capture-the- underlying-logic of my own scripts, for later
understanding/editing.
It reminds me of the undisciplined hacking of BASIC, before the days of
*STRUCTURED* programming. Where can I find documentation on this problem?

I have a very simple solution to your problem:

It's called "comments."

[Rich]

Post by Poprocks

Post by f***@gmail.com
single author Slackware had a unique/superior documentation method.
That's why several single-author systems have used it as their basis.
It's very frustrating when I can't understand the simplest little script
that I wrote a few days ago.

[...]

Post by f***@gmail.com
There's some good documentation by the unix originators, who went on to
refine it towards plan9...inferno...but I can't find any methods to
capture-the- underlying-logic of my own scripts, for later
understanding/editing.
It reminds me of the undisciplined hacking of BASIC, before the days of
*STRUCTURED* programming. Where can I find documentation on this problem?

It's called "comments."

Indeed. And, the OP should also consider that when writing the
comments, he should document the "why" something is being done, not
"what" is being done.

The "what" is almost always self explanatory from the code.

The "why" the code is doing what the code is doing is often not
immediately obvious from the "what" the code is doing, and so comments
documenting the "why" something was done are often much superior to
those that just say what is occurring.

[Auric__]

Post by Rich

Post by Poprocks

Post by f***@gmail.com
single author Slackware had a unique/superior documentation method.
That's why several single-author systems have used it as their basis.
It's very frustrating when I can't understand the simplest little
script that I wrote a few days ago.

[...]

Post by f***@gmail.com
There's some good documentation by the unix originators, who went on to
refine it towards plan9...inferno...but I can't find any methods to
capture-the-underlying-logic of my own scripts, for later
understanding/editing.
It reminds me of the undisciplined hacking of BASIC, before the days
of *STRUCTURED* programming. Where can I find documentation on this
problem?

It's called "comments."

Indeed. And, the OP should also consider that when writing the
comments, he should document the "why" something is being done, not
"what" is being done.
The "what" is almost always self explanatory from the code.
The "why" the code is doing what the code is doing is often not
immediately obvious from the "what" the code is doing, and so comments
documenting the "why" something was done are often much superior to
those that just say what is occurring.

That's not to say the "what" isn't important. A *short* summary of what's
happening means that you won't *need* to read through the code.

[Lew Pitcher]

Post by Poprocks

Post by f***@gmail.com
single author Slackware had a unique/superior documentation method.
That's why several single-author systems have used it as their basis.
It's very frustrating when I can't understand the simplest little script
that I wrote a few days ago.

[...]

Post by f***@gmail.com
There's some good documentation by the unix originators, who went on to
refine it towards plan9...inferno...but I can't find any methods to
capture-the- underlying-logic of my own scripts, for later
understanding/editing.
It reminds me of the undisciplined hacking of BASIC, before the days of
*STRUCTURED* programming. Where can I find documentation on this problem?

It's called "comments."

Well, it's usually /more/ than that. You need to document the code from the
inside and the outside. The "from the inside" should explain the "whats
going on" and "what we expect at this point", and the "why we did it this
way" and "why we expect what we do" of the code. The "from the outside"
should explain what the code does, at a macro level, how to use the code,
what caveats apply, and what (if any) are the known gotcha's and bugs.

We document the code from the inside with comments. Comments need to be
meaningful. Consider a basic binary search:

for (midpt = (lowpt+highpt)/2;
array[midpt] != key && highpt > lowpt;
midpt = (lowpt+highpt)/2)
{
if (key > array[midpt])
lowpt = midpt + 1;
else
highpt = midpt - 1;
}

You could comment it like this:
for (midpt = (lowpt+highpt)/2; /* start here */
array[midpt] != key && highpt > lowpt; /* stop here */
midpt = (lowpt+highpt)/2) /* test here */
{
if (key > array[midpt])
lowpt = midpt + 1; /* add one */
else
highpt = midpt - 1; /* subtract one */
}

or, you could comment it like this:
/* LOOP through search UNTIL match found OR no elements left to search */
for (midpt = (lowpt+highpt)/2; /* start in the middle */
array[midpt] != key && highpt > lowpt; /* not found & in bounds */
midpt = (lowpt+highpt)/2) /* compute new midpoint */
{ /* ============================ **
** array[midpt] was NOT a match **
** ============================ */
if (key > array[midpt])
lowpt = midpt + 1; /* narrow search to between here and high */
else
highpt = midpt - 1; /* narrow search to beween low and here */
}
/* loop terminates when entry found OR no more array to search */

The first is how much code is "commented". The second tries to explain the
what and why, not the literal /how/.

We document the code from the outside with man pages. Until Unix, most API
and application manuals were either too terse or too verbose. The Unix
manpage format lends itself to documenting the essentials of the code, from
the outside, giving everthing from use to usage to bugs to references and
associated tools. You know that the manpage is well-written when you can use
it exclusively, instead of having to deep-dive into the code.

HTH

[Lew Pitcher]

On August 21, 2020 14:16, Lew Pitcher wrote:
[snip]

Post by Lew Pitcher
We document the code from the outside with man pages. Until Unix, most API
and application manuals were either too terse or too verbose.

I worked most of my career with IBM mainframes, and had to "suffer" with
IBM's manuals. The /only/ IBM manual that matched the Unix manuals for
clarity was the "IBM System/370 Principles of Operations".

[snip]

[Aragorn]

Post by Lew Pitcher
[snip]

Post by Lew Pitcher
We document the code from the outside with man pages. Until Unix,
most API and application manuals were either too terse or too
verbose.

I worked most of my career with IBM mainframes, and had to "suffer"
with IBM's manuals. The /only/ IBM manual that matched the Unix
manuals for clarity was the "IBM System/370 Principles of Operations".
[snip]

"This page intentionally left blank."


:p

[Poprocks]

Post by Lew Pitcher
[snip]

Post by Lew Pitcher
We document the code from the outside with man pages. Until Unix, most API
and application manuals were either too terse or too verbose.

I worked most of my career with IBM mainframes, and had to "suffer" with
IBM's manuals. The /only/ IBM manual that matched the Unix manuals for
clarity was the "IBM System/370 Principles of Operations".

Professor Kevin O'Kane has a really interesting video on what I *though*
was the System/370 after reading your post, but was actually on the
System/360.

Either way, it's an interesting watch:

[Henrik Carlqvist]

Post by Lew Pitcher
/* LOOP through search UNTIL match found OR no elements left to search */
for (midpt = (lowpt+highpt)/2; /* start in the

middle */

Post by Lew Pitcher
array[midpt] != key && highpt > lowpt; /* not found & in bounds */
midpt = (lowpt+highpt)/2) /* compute new

midpoint */

Post by Lew Pitcher
{ /* ============================ **
** array[midpt] was NOT a match **
** ============================ */
if (key > array[midpt])
lowpt = midpt + 1; /* narrow search to between here and high */
else
highpt = midpt - 1; /* narrow search to beween low and here */
}
/* loop terminates when entry found OR no more array to search */

I agree that your second example of comments are easier to read. On the
other hand, in my experience, it is not uncommon to stumble upon code
which has evolved to a state where its comments are old and misleading.

With that experience I prefer to keep few comments and make functions and
variable names self-explanatory. To continue with a third version of your
example:

/* LOOP through search UNTIL match found OR no elements left to search */
for (middle_point = (low_point+high_point)/2;
array[middle_point] != key && high_point > low_point;
middle_point = (low_point+high_point)/2)
{
/* array[middle_point] was NOT a match */

if (key > array[middle_point])
{
/* narrow continued search to between here and high */
lowpoint = middlepoint + 1;
}
else
{
/* narrow continued search to beween low and here */
high_point = middle_point - 1;
}
}

In the example above some of your comments has been replaced with more
explaining variable names. I also removed the last comment which where
redunant to the first comment. The reason that I did choose to keep the
first comment was that it was close to the code that it described, if you
would change that code it would be easier to see that also the comment
should be changed.

regards Henrik

[Lew Pitcher]

Hi, Henrik

Post by Lew Pitcher

Post by Lew Pitcher
/* LOOP through search UNTIL match found OR no elements left to search */
for (midpt = (lowpt+highpt)/2; /* start in the

middle */

Post by Lew Pitcher
array[midpt] != key && highpt > lowpt; /* not found & in

bounds

Post by Lew Pitcher

Post by Lew Pitcher
*/
midpt = (lowpt+highpt)/2) /* compute new

midpoint */

Post by Lew Pitcher
{ /* ============================ **
** array[midpt] was NOT a match **
** ============================ */
if (key > array[midpt])
lowpt = midpt + 1; /* narrow search to between here and high

*/

Post by Lew Pitcher
else
highpt = midpt - 1; /* narrow search to beween low and here */
}
/* loop terminates when entry found OR no more array to search */

I agree that your second example of comments are easier to read. On the
other hand, in my experience, it is not uncommon to stumble upon code
which has evolved to a state where its comments are old and misleading.
With that experience I prefer to keep few comments and make functions and
variable names self-explanatory. To continue with a third version of your
/* LOOP through search UNTIL match found OR no elements left to search */
for (middle_point = (lo>
regards Henrikw_point+high_point)/2;
array[middle_point] != key && high_point > low_point;
middle_point = (low_point+high_point)/2)
{
/* array[middle_point] was NOT a match */
if (key > array[middle_point])
{
/* narrow continued search to between here and high */
lowpoint = middlepoint + 1;
}
else
{
/* narrow continued search to beween low and here */
high_point = middle_point - 1;
}
}
In the example above some of your comments has been replaced with more
explaining variable names. I also removed the last comment which where
redunant to the first comment. The reason that I did choose to keep the
first comment was that it was close to the code that it described, if you
would change that code it would be easier to see that also the comment
should be changed.

Yes. I agree with your changes.

Your version makes my point better than mine did, I think.

[Mike Small]

Post by f***@gmail.com
I suspect/hope there's a few fundamental rules to solve this problem.
And definitely NOT practice-makes-perfect.
IMO there's 2 ways of solving a problem: by association, like a football-player
or my dog, or a M$pook user, and then there's deduction: eg. where the
MINIMALIST underlying principals, like mass, length, time solve Newtonian
physics questions; or bits, bytes, files, directories in the unix family
consistently structure the solutions.
There's some good documentation by the unix originators, who went on to
refine it towards plan9...inferno...but I can't find any methods to capture-the-
underlying-logic of my own scripts, for later understanding/editing.
It reminds me of the undisciplined hacking of BASIC, before the days of
*STRUCTURED* programming. Where can I find documentation on this problem?

Maybe you are someone who might become an enthusiast of literate
programming:

https://en.wikipedia.org/wiki/Literate_programming

That doesn't list shell script as a language with an existing
implementation, but, assuming there's really nothing out there for
it, and supposing you become very dedicated to the approach and
are inclined to depart from norms in a similar way to how GNU
developers of the past have to solve other problems, m4 might be
a means to get there. But that's not at all in the style of Slackware,
it adding an extra layer and a lot of up front work.