3.11 Stack-Effect Comments

慣例により、 定義名の後のコメントはスタック効果を説明します。 ‘--’ の前の部分は、 定義の実行前のスタックの状態、 つまりコロン定義に渡されるパラメータを説明します。 ‘--’ の後ろの部分は、 定義の実行後のスタックの状態、 つまり定義の実行結果です。 スタック・コメントには、 定義がアクセス、 または、変更する、 (訳注: 定義の外部から見える、 )スタック項目のみを記述します。

たとえ スタック効果が ( -- ) (訳注: スタックに何の効果も及ぼさない)であっても、 あなたは、 すべての定義に正しいスタック効果を記述するべきです。 また、 より複雑なワードには説明的なコメントを追加する必要があります(通常、 これは : の後ろに続けます)。 これを行わないと、 あなたコードの行動は解読不能になります(なぜなら、 とある定義を理解するためには、 全ての定義を辿るハメになるから)。

研究課題(assignment): 例えば swap のスタック効果は、 x1 x2 -- x2 x1 のように記述できます。 同様に、 - や drop や dup や over や rot や nip や tuck のスタック効果を書いてみましょう。 ヒント: 書けたら、 このマニュアルに書いてあるスタック効果と合っているかどうかチェックしましょう(see Word Index)。

プログラマーは、 コロン定義内のさまざまな場所に、 その場所のスタックの内容を説明するコメント(スタック・コメント)を挿入することがあります。 つまり、 スタック効果コメントの最初の部分のようなものです。 例えば以下のようなのです

: cubed ( n -- n^3 )
   dup squared  ( n n^2 ) * ;

この場合、 ワードが十分に単純であるため、 スタック・コメントは割と余計です。 あなたが、 読みやすさを高めるためにそのようなコメントを追加することが良いと思った場合、 ワードをいくつかの単純なワードにファクタリング(因数分解)することも検討する必要があります(see Factoring)。 ファクタリングにより、 通常はスタック・コメントが不要になります。 ただし、 あなたが結果としてリファクタリングしないことに決めた場合は、 そのようなコメントがある方が、 無いよりも良いです。

標準や、 このマニュアルや、 多くのプログラムの、 スタック効果およびスタック・コメント内のスタック項目の名前は、 Fortran やハンガリアン記法と同様に、 型プレフィックスによって型を指定します。 最も頻繁に使用されるプレフィックスは以下のとおりです:

n

符号付き整数

u

符号なし整数

c

文字(character)

f

二値フラグ(Boolean flags)。 つまり false または true

a-addr,a-

セル・アライメント・アドレス

c-addr,c-

文字(char)アライメント・アドレス(注意: Windows NT では文字(char)は 2 バイトになる場合があることに注意)

xt

実行トークン(Execution token)。 セルと同一サイズ

w,x

セル(cell)。 セルには整数またはアドレスを含めることができます。 通常は 32ビットまたは 64 ビットまたは 16 ビットを必要とします(プラットフォームと Forth システムによって異なります)。 cell は一般には machine word として知られていますが、 Forth では word という用語はすでに別の意味を持っています。

d

符号付き2倍長整数(signed double-cell integer)

ud

符号無し2倍長整数(unsigned double-cell integer)

r

浮動小数点数(Float)(FP スタック上に置かれる)

より完全なリストは Notation にあります。

研究課題(assignment): あなたがここまでで記述したすべての定義に対してスタック効果コメントを記述してみましょう。