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.
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.
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'.
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'.
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
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.
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.