Hi,

Are you recovering an unknown FORTH code?

Looking to understand the meaning of the FORTH words in this code?

Well, I have developed a mill, in PHP, which will read this code and document it in a fraction of seconds!

https://eforth.arduino-forth.com/index/doc/

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

On Sunday, 26 November 2023 at 21:26:24 UTC, Marc Petremann wrote:

Hi,

Are you recovering an unknown FORTH code?

Looking to understand the meaning of the FORTH words in this code?

Well, I have developed a mill, in PHP, which will read this code and document it in a fraction of seconds!

https://eforth.arduino-forth.com/index/doc/

Great idea.
If I understand it correctly,
the program adds links to the words used to the software and known.

Should be a great tool for people who start with Forth.

And if this could be open source,
people could adapt it to other Forths,
e.g. Swiftforth and VFX and more.

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

I tested it with code snippets from F83 and an old but short 8QUEEN solver. Your tool did not _document_ anything, but added hyperlinks to words,
pointing deeper into your own Forth systems. Good for you.

But thanks anyway for releasing your tool to the public.
You might be interested in HolonForth for comparison.

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

In article <unnet8$2ml74$[email protected]>, dxf <[email protected]> wrote:

On 11/01/2024 10:51 am, Hans Bezemer wrote:

On Monday, November 27, 2023 at 9:16:47 AM UTC+1, minforth wrote:

I tested it with code snippets from F83 and an old but short 8QUEEN solver. >>> Your tool did not _document_ anything, but added hyperlinks to words,
pointing deeper into your own Forth systems. Good for you.

But thanks anyway for releasing your tool to the public.
You might be interested in HolonForth for comparison.

Yeah, it's useless. I'd write something like that in zero flat.
However, I had good results with feeding code to ChatGPT
and let it figure out what it does. I stripped all comments
from it - but I guess well named words might give it enough
hints.

I won't call it documentation either, but for figuring out what
zero commented code actually does functionality wise, I think
it's quite handy.

App code I write are near zero commented. This is less problematic
in forth where functions tend to be short. Unless a function is very >obscurely named (Will Baden?), forth is largely self-documenting.
Nor is 'tricky' code really a problem. By the time one realizes it
was tricky, one will add the comment. If OTOH one never comes back to
it, who is there to care? I appreciate there may be external reasons
to add comments e.g. to impress the audience or the customer demanded
it. But that's more about pleasing others. IIRC Moore's source for >ColorForth had no comments.

Moore is no shining example.
Moore doesn't intend to write portable programs, and he maintains
them himself, or rather he rewrites.
Also Moore's political ideas are abhorrent and his associating
with a patent troll was a financial miss.
You can learn things from Moore, but you have to decide what is
good and what less good.

One of the reason libraries in Forth are problematic, that the skill
to properly document API's is underdeveloped. Probably because
many people think that ( d n -- ud) is sufficient documentation.
Forth is only in part self-documenting if the functions are
brilliantly named, requiring a skill not wide spread.

There are two reasons to document, usage and maintenance.
I want ciforth to be used, so every word is meticulously documented.
I have much (40 year) professional experience in maintenance.
Maintenance documentation especially regards the overlooked border
cases makes out the value of a program. Consequently my Forth programs
are worth more to a c-programmer, than most Forth programs are to a
Forth programmer.

Groetjes Albert
--
Don't praise the day before the evening. One swallow doesn't make spring.
You must not say "hey" before you have crossed the bridge. Don't sell the
hide of the bear until you shot it. Better one bird in the hand than ten in
the air. First gain is a cat purring. - the Wise from Antrim -

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

sjack wrote:

[..]

I by habit usually add useless comments. It's something I
can do unthinkingly while I contemplate some aspect or usage
of the code just written; fingers like to stay busy.

Do you change these comments when you afterwards change the code?

My four rules are:
1. At the top of the file there is an explanation WHAT
the program is going to do, which METHOD it uses (references!)
and, not in depth, HOW it is doing it.
2. Every word has a stack comment.
3. At the end of the file there is word which runs a small example,
exercising the code. The output is self-explaining, or it
refers to [1].
4. (optional) Internal words, if any, are marked as such and
preferably hidden. This allows the user to skip such words
in the first reading.

-marcel

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

In the past, we had code reviews as part of the product release.
Experienced engineers from the service department went through
the source code of the system to check that the code was
understandable and serviceable, e.g. remotely. The result was
often very sobering, but very positively instructive for everyone.

As an individual programmer in your one-man-show, you need more
discipline. But probably every old hand in the business has sat
in front of their own old code and puzzled over it.

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

In article <unpqub$35agg$[email protected]>, dxf <[email protected]> wrote:

On 12/01/2024 5:34 am, mhx wrote:

sjack wrote:

[..]

I by habit usually add useless comments. It's something I
can do unthinkingly while I contemplate some aspect or usage
of the code just written; fingers like to stay busy.

Do you change these comments when you afterwards change the code?
...

Good point. I find comments get included on subsequent revisions, >particularly as overall program complexity increases. These tend
to be one-liners at the beginning of a definition. More a reminder
than an explanation. I did 'technical writing' in my career aimed
at new readers. Nothing like that. I'd find it tedious.

Right. The more effort is expended, the more valueable the result
is.

Groetjes Albert

--
Don't praise the day before the evening. One swallow doesn't make spring.
You must not say "hey" before you have crossed the bridge. Don't sell the
hide of the bear until you shot it. Better one bird in the hand than ten in
the air. First gain is a cat purring. - the Wise from Antrim -

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

In article <[email protected]>,
minforth <[email protected]> wrote:

In the past, we had code reviews as part of the product release.
Experienced engineers from the service department went through
the source code of the system to check that the code was
understandable and serviceable, e.g. remotely. The result was
often very sobering, but very positively instructive for everyone.

As an individual programmer in your one-man-show, you need more
discipline. But probably every old hand in the business has sat
in front of their own old code and puzzled over it.

A familiar situation. I spread out this puzzlement.
As soon as I cannot understand a comment at first glance, I
improve it. Don't be surprised if texts are reformulated a dozen
times. As chairman Mao has taught us, an article has to be
rewritten about seven times before it is good.

Groetjes Albert
--
Don't praise the day before the evening. One swallow doesn't make spring.
You must not say "hey" before you have crossed the bridge. Don't sell the
hide of the bear until you shot it. Better one bird in the hand than ten in
the air. First gain is a cat purring. - the Wise from Antrim -

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

In article <[email protected]>,
mhx <[email protected]> wrote:

sjack wrote:

[..]

I by habit usually add useless comments. It's something I
can do unthinkingly while I contemplate some aspect or usage
of the code just written; fingers like to stay busy.

Do you change these comments when you afterwards change the code?

My four rules are:
1. At the top of the file there is an explanation WHAT
the program is going to do, which METHOD it uses (references!)
and, not in depth, HOW it is doing it.
2. Every word has a stack comment.
3. At the end of the file there is word which runs a small example,
exercising the code. The output is self-explaining, or it
refers to [1].
4. (optional) Internal words, if any, are marked as such and
preferably hidden. This allows the user to skip such words
in the first reading.

Sensible rules.
I expand point 3 a bit with REGRESS.
The REGRESS exercise a words, (call it a test), with expected
outcome, and not restricted to external words.

-marcel

Groetjes Albert
--
Don't praise the day before the evening. One swallow doesn't make spring.
You must not say "hey" before you have crossed the bridge. Don't sell the
hide of the bear until you shot it. Better one bird in the hand than ten in
the air. First gain is a cat purring. - the Wise from Antrim -

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)