The following convention reflects mainly my ideas, and was partly
inspired by Stallman and Moore.
It is a convention for writing low level comment, e.g. the comment
accompagnying words in Forth.
It has been used in other languages than Forth, in particular LISP.
Stallman is the main writer of EMACS and well known for the Free Software
Foundation and GNU.
I have adapted it to Forth, in particular regarding the return values of
words. The convention applies to the comment explaining a Forth word.
Comment at the start of modules -- or however the source is subdivided --
is not part of this.
Speak naturally.
The first rule is that comment consists of grammatical sentences,
such that the only reason to not
understand it is lack of familiarity with the subject.
Concise language is favoured, but too terse abbreviations are not.
It is placed before the definition of a word.
I
Parameters are in capitals (Stallman)
The second rule is that a word in capitals means a parameter.
Those parameters appear in the text in the same order as on the stack,
as do the return parameters.
The separation between the two kinds of parameters is natural,
by use of the word 'return', a colon or the word 'leave'.
II
Surround parameters with extra spaces (Moore)
We may want an alternative to the capitals convention if there
are no capitals in the Forth, such as in colorforth,
but mainly when capitalization has already some meaning.
Moore's way is to surround the parameters with an extra pair
of spaces.
Those parameters appear in the text in the same order as on the stack,
as do the return parameters.
The separation between the two kinds of parameters is natural,
by use of the word 'return', a colon or the word 'leave'.
Types are inferred.
The third rule is about the type of the parameter.
Names can mostly be choose such that the type is clear.
So for calculations one will often have names that are one to one
with classical stack descriptions, like DOUBLE.
In particular if the name of a defining word is used (e.g. VARIABLE)
a parameter of that type is required.
All names ending in NAME or STRING are an address, length pair containing
a string.
If a verb is capitalised, in particular within quotes, this means a truth
value, or flag in mundane Forth parlance.
The verb is the carrier of the meaning of truth.
If there is not enough information to infer the type,
it must be stated explicitly.
A general remark.
The point of view taken in descriptive comment is that it tells what the
Forth word does for you, not how it accomplishes it.
This is of course common knowledge, but it bears repeating.