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/

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.

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.

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.

On 11/01/2024 12:05 pm, dxf 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.

p.s. I find there's a beauty in code uncluttered by useless comments.
(Don't get me started on 'auto-doc' forth source :)

In article <unnet8$2ml74$2@dont-email.me>, dxf <dxforth@gmail.com> 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 -

dxf wrote:

> p.s. I find there's a beauty in code uncluttered by useless comments.
> (Don't get me started on 'auto-doc' forth source :)

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.

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

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.

mhx wrote:
> Do you change these comments when you afterwards change the code?

For sure,don't like misleading comments. I don't find it a bother to
change comments when code change. Did much typing before programming;
keyboard is like an extension; think and its printed.

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.

In article <aa3f535e4950f466418da096be170835@www.novabbs.com>,
mhx <mhx@iae.nl> 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 -

In article <unpqub$35agg$1@dont-email.me>, dxf <dxforth@gmail.com> 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 -

In article <d47a5e761be02ef418375255f392aba5@www.novabbs.com>,
minforth <minforth@gmx.net> 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 -

On 11/01/2024 8:58 pm, albert wrote:
> ...
> 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.

Program documentation and source commenting are different things and
should be kept separate. Before venturing to employ either there ought
to be a real prospect it will be used - not just hope. Shadow screens
provided in some old forths? I never read them.