どのプログラム入門書籍にも、コメントを書きましょう、と書いてあるものですが、実際にコメントをどう書けば良いか、というのはなかな分りにくいものです。
--> 結果
スクリプトを見ればすぐに分る事を書かない、という事です。
逆に言えば、スクリプトを見ただけでは分らない、又は分りにくい事を書くものがコメントと言えます。
まず、用語説明やリファレンスに書かれているような事は、あまり書く意味が無いといえます。分らない場合も、リファレンスを見れば分るのですから。
つまりAppleScriptがなにをしているかではなく、スクリプトの作者(つまり自分)がなにをしようとしているか、を書くことが大事です。
コメントは、より人間に分りやすくなるように書くものですから、人間よりの情報を書かなくては、あまり分りやすくはならない、という事です。
もちろん備忘録として、AppleScriptがなにをしているか、を書く事が悪いという訳ではありません。
ifなどのブロック開始前に書くべきか、開始直後に書くべきか。
elseの場合は、前に書くとifブロックの中に書く事になってしまうので、elseの後に書く方がいいと思います。となると、
miやBBeditなどのコードエディタでAppleScriptを書く場合は、ハンドラにジャンプする機能が付いているので、ハンドラの内側に書く方がいいでしょう。
構文確認時にコメントは全部省かれるようなので、コメントが内側にある事による速度差は、無いようです。
ハンドラの説明は、用語説明の読み方(命令編)を参考に、ある程度は用語説明に合わせるのがいいんではないかと思います。
完全に同じように描く必要はありません。と言っても、私自身もあまり徹底はしていませんが。
仮引数:整数 -- 簡単な解説
Result: リスト -- 簡単な解説結果は、-->
コメントから、自動的にマニュアルを生成するアプレットを作っておく。
javadocみたいなもん。