★★★このドキュメントは編集中です。★★★
サンプルの取捨選択や説明の仕方について。
サンプル作成の基準は以下。
サンプルは凝ったものである必要はない。しかし、ただ構文をただなぞっただけでは意味がない。
構文を理解させるのは最低限、その上で、その機能がどのような局面で利用されるべきものかが実感できるようなサンプルが好ましい。
もっとも、それでサンプルが複雑なものになってしまうのは、それはそれで好ましくない。1.のルールを維持するためにも、ある程度は文章で「使いどころ」を補うことを検討する必要があるだろう。
記事の中で説明しているキーワードや概念、機能について、ただ説明だけで終わり、というのは原則不可。
どんなに分かりやすい解説であっても、読者が理解するうえで、実際のサンプルコードに勝る手掛かりはないからだ。
ひとつのキーワードや機能について、サンプルはかならずひとつ以上。
対象読者にもよるが、少なくとも入門者向けの記事であれば、コメントを読んでいくだけでも最低限、コードの流れが追える程度のコメントを加えておくのが望ましい（もちろん、一行一行にコメントが必要、という意味ではない）。
あくまで流れをざっと理解させるのが目的であるので、コメントは一箇所につき一行に収めたい。
つまり、一箇所一箇所で細かな説明をするべきではない。あくまでそこでなにをしているのかが流し読みできるようにするのがコメントの目的だ。
あくまでコード内のコメントは、あくまで主テーマ以外に本文解説を割かないための（解説を散漫にしないための）補足にすぎない。
本来の目的であったテーマについての解説は、本文側できちんと行うべきだ。
そもそもサンプルを登場させたのはあるテーマを説明するためのものだったはずなのだから、これを説明せずに、ただ「サンプルとそのコメントだけを見よ」というのは本末転倒である。
コード内コメントはサンプルそのものの説明、本文説明は汎用的な説明と、切り分けるのも一つの方法。
その記事が、サンプル集のような記事でない限り、サンプルはあくまでライブラリやキーワードを理解するための補足的な内容にすぎない。よって、サンプルの説明に終始するのは本末転倒。
最終的には、ライブラリやその機能を読者が理解して、「自分の」アプリケーションで応用できるまでを解説するのが目的であるはずだ。
サンプルコードには、いかにシンプルとは言っても、多くの場合、本来のポイントとは関係ないコードはいくらでも含まれている。
その中で、著者がポイントと考えている部分をきちんとみせてやることは重要だ。
そのような箇所は太字指定にするのもありだと思うし、本文説明とリンクしているならば、できる限り、（1）（2）...のような番号付けをして、解説がサンプルコードのどの部分に対応しているのかを明確にしておきたい。
最初に、コードの細かな流れや構文説明などを延々と進め、最後にまとめのようにサンプルコードを掲載している原稿を見かけるが、これはNG。
コードがまだ登場していない状態で、その内容を説明されても読み手は理解できない。
そもそもせっかく具体的なイメージを沸かせるために、サンプルを掲載しているはずなのに、サンプルがオマケのような位置づけになってしまっていて勿体ない。
サンプルを紹介する場合には、最初の説明は
程度の概要に留め、早い段階でサンプルコードを見せるべきである。具体的な、細かい説明はその後で良い。
掲載すべきコードが極端に長い場合、必ずしも最初からすべてのコードを見せるべきではない。
その場合は、サンプルの構造が分かるような概念図やリスト、表を見せた上で、断片的なコードを順に抜粋していくという方法もあるだろう（最初に概念図、というのがキモ）。
＃もちろん、断片的なコードを紹介する場合にも、概要→コード→具体的な説明は基本である。
その上で、もし誌面が許すならば、最後にコード全体をまとめて見せても良い。もちろん、これは必須ではなく、断片的に見せたことでコード全体が把握しにくいと判断した場合のみ。 誌面が許さない、または読者がそれなりに中級者以上である場合には、「ダウンロードサンプルからコードを直接参照」とするのもあり。
サンプルは基本的にサーバ（ローカルマシン）に配置すれば、すぐに動作する状態にしておくのが望ましい。
そのままでは動作しない場合には、最低限、サンプルを動作するための手順を、記事内でも紹介しておくこと。
＃それが難しい場合には、Readme的なドキュメントを配布サンプルに収録しても構わない。
また、記事内のコードリストにも、かならず配布サンプル上のファイル名（必要に応じてパスも）を併記されたい。
記事の性質にもよるが、多くの場合、記事にコードのすべてを掲載することは稀だ。
読者が全体のコードを確認したいと思った場合にも、ファイル名を明記してあれば、参照は容易になる。
＃そしてもちろん、著者も気軽に?抜粋できるようになるだろう。
書籍や記事のレイアウトにもよるが、1行あたりの桁数はおおよそ60桁程度。紙面上、折り返し記号を入れることもできるが、見やすさの観点からも、できるだけ利用は最小限にしたい。
また、折り返し箇所は機械的に決めるのではなく、意味ある個所で区切るべき。
