技術ノート 0

Lua 技術ノートの書き方

Lua技術ノートの作成に関する公式なガイドラインはありません。アップルの著者向けガイドや、技術ノートの要素について（Macintosh 技術ノートより）を読むことはできますが、これらのドキュメントは技術ノートがどのようなものかのアイデアを得るためだけに読んでください。Lua技術ノートははるかに非公式なものです。

以下は、LTNの書き方に関する個人的な（そして自己言及的な！）見解です。

LTNの書き方

by ルーベン・トーマス

概要

LTNは以下の構造を持つべきです。

概要
問題点 - 動機と記述
解決策 - 説明
解説と正当性
弱点と改善提案
結論

問題点

Luaは、多くのプログラミング問題を解決するための非常に経済的なツールです。残念ながら、その経済性と設計の柔軟性は、初心者にとって混乱を招く可能性があります。彼らは、単純でエレガントな解決策が見つかるはずの場所で、ぎこちない解決策を見つけたり、さらに悪いことに、まったく見つけることができない可能性があります。ほとんどの言語のユーザーが単にそれらでプログラミングするのとは異なり、Luaプログラマーは、Luaを埋め込んだり、インターフェースしたり、さらには変更したりしたいと考えることがよくあります。

tolua、CGILua、LuaSocketなど、これらのニーズの多くを満たすためにさまざまなライブラリやツールが成長してきました。ただし、いくつかのニーズはより抽象的であり、ツールやライブラリでは簡単に満たすことができません。たとえば、「LuaをC++プログラムに統合するにはどうすればよいか？」「Luaを別の言語とインターフェースするにはどうすればよいか？」「ガーベジコレクションのためにゲームを一時停止させないようにするにはどうすればよいか？」などの質問です。これらの質問には、ハウツーのようなドキュメントで対処するのが最適であり、これがLTNシリーズの目的です。しかし、このニーズを満たすために、LTNはどのように書くべきでしょうか？

LTNは以下のプロパティを持つ必要があります

実用的なニーズに対処する必要があります。経験則として、LTNを書きたいと思うなら、それはおそらく実用的なニーズに対処しているのでしょう。ただし、他の人がそれに対処する問題に対する解決策を求めている場合は、さらに良いです。
簡潔である必要があります。これにより、他の人ができるだけ早く、含まれる知識を読み、理解し、使用できるようになります。あるいは、それが彼らにとって役に立たない場合は、それを破棄できるようになります。この一部として、LTN全体を読んでそれが自分に必要なものかどうかを知る必要がないようにする必要があります。
権威がある必要があります。不正確または考え抜かれていないLTNは、何もないよりも悪い可能性があります。繰り返しますが、LTNを書きたいと思うなら、おそらく自分が何を言っているのか知っているでしょう。Luaの設計者はこのシリーズのエディターを務めており、これも役に立ちます。

解決策

解決策には、形式と内容の2つの部分があります。内容は作成者に任されています。LTNの推奨形式は次のとおりです。

概要: LTNを要約します。
問題点: 問題の動機：なぜそれが重要なのか。明確な記述で終わります。これは、あなたと読者の両方が焦点を絞るのに役立ちます。このセクションの終わりまでに、読者はLTNが自分にとって役立つかどうかを知っているはずです。
解決策: 必要以上に詳しく説明せずに、解決策を説明します。このセクションの終わりまでに、急いでいる読者は解決策を実行できるようになっているはずです。
解説: なぜ自分の解決策をそのように設計したのかを説明し、正当化します。これにより、懐疑的な人を納得させ、慎重な人に、自分の解決策が優れており、自分が何をしているのかを知っていることを安心させるでしょう。周辺事項や重要でない微妙な点は、ここで探求できます（ただし、関連性を維持してください！）。
弱点: 自分の解決策の弱点について説明し、それが成功にとって重要でない理由を述べ、将来の改善を提案します。ここが、懐疑的な人に自分が詳しいことを本当に納得させる場所です。
結論: 要約し、問題と解決策についてより広い視点を与えます。

解説

この構造は、優れた技術文書の標準的な慣例に従っています。シンプルな5部構成の構造は、簡潔さを促し、考えられるほとんどのLTNに適合し、作成者と読者が従うのが簡単で、ほとんどの読者が上から始めて十分に読むまで、LTNから必要なものをすべて得ることができます。

弱点

すべてのサイズが1つに適合することはありません。提案された構造は、一部の人にとっては詳細すぎたり、他の人にとっては不十分だったり、他の人にとっては単に関連性がない場合があります。私は実際に書く方法については何も述べていません（この点に関する明確で簡潔なガイダンスについては、ストランクとホワイトの「The Elements of Style」を参照してください）。それにもかかわらず、ほとんどの著者がこの構造に従えば、LTNの作成がより簡単になり、読者は、特にその共通の構造のために、LTNが読みやすくなるでしょう。

結論

Luaの優れた点は、特定の問題に対する解決策ではなく、一般的に適用可能なメカニズムを提供することにあります。それにもかかわらず、Luaを使用する際に多くの問題が頻繁に発生します。より具体的なもののいくつかは、利用可能なさまざまなライブラリやツールによって対処されています。LTNは、より抽象的な種類のいくつかに取り組もうとしています。このLTNは、LTNをより役立つようにするための構造を提案しています。

最後に、LuaプログラマーとLTN作成者は、Luaの第一のルール「Luaで実行する」を常に念頭に置く必要があります。Luaは、ほとんどの場合、問題を解決するために必要なツールを提供します。それらをどのように使用するかを確認するだけです。Lua APIを真剣に使用する必要はめったになく、Lua自体を変更する必要はさらにめったにありません。3つの枢要な美徳の観点から、Luaは怠惰さを忍耐よりも重視し、忍耐を傲慢さよりも重視します。しかし、もちろん、傲慢さはまさにLTNを書くために必要なものです！

最終更新日: 2004年3月18日木曜日 14:03:37 BRT by lhf.