「サンプルについて」の編集履歴（バックアップ）一覧はこちら
「サンプルについて」(2010/08/24 (火) 11:00:47) の最新版変更点
追加された行は緑色になります。
削除された行は赤色になります。
サンプルの取捨選択や説明の仕方について。
*サンプルの選択の仕方
サンプル作成の基準は以下。
+最大限、シンプルであるか
+対象となる命令の使いどころを理解させるのに十分であるか
サンプルは凝ったものである必要はない。しかし、ただ構文をただなぞっただけでは意味がない。
構文を理解させるのは最低限、その上で、その機能がどのような局面で利用されるべきものかが実感できるようなサンプルが好ましい。
もっとも、それでサンプルが複雑なものになってしまうのは、それはそれで好ましくない。1.のルールを維持するためにも、ある程度は文章で「使いどころ」を補うことを検討する必要があるだろう。
*基本的にはすべての説明に何らかのサンプルがあるべき
記事の中で説明しているキーワードや概念、機能について、ただ説明だけで終わり、というのは原則不可。
どんなに分かりやすい解説であっても、読者が理解するうえで、実際のサンプルコードに勝る手掛かりはないからだ。
ひとつのキーワードや機能について、サンプルはかならずひとつ以上。
*サンプルには必ず実行結果も掲載
コードだけを見よ、では不十分。サンプルではその結果を見せることで初めて、読者がイメージを持つことができる場合も多い。
結果のあるサンプルで結果をきちんと掲載するのはもちろん、結果のないサンプルもできるだけ結果が見えるような形にするべきである。
たとえば、クラスの説明ならば、単にクラスを定義するだけでなく、クラスをインスタンス化し、呼び出すコードまでが望ましい。
＃もちろん、説明の方法によっては、クラスの定義と呼び出しの説明は別々にした方が良いこともあるかもしれない。
コマンドなどを見せる場合も同様。結果を見せることで、読者はその結果が等しいことで安心しながら、手元の作業を進められる。
*実行結果が環境などの要因で異なる場合
必ずその旨を明記すべき。特に初学者向けの記事の場合は、実行結果が手元で試した時と違うと、読者が混乱したり不安に陥ったりする原因にもなる。
個別に記載するのが冗長である場合には、書籍では「本書の読み方」などで、個別記事の場合は記事先頭などで、フォローするのもありだろう。
*コメントはできるだけ細かく加えること
対象読者にもよるが、少なくとも入門者向けの記事であれば、コメントを読んでいくだけでも最低限、コードの流れが追える程度のコメントを加えておくのが望ましい（もちろん、一行一行にコメントが必要、という意味ではない）。
あくまで流れをざっと理解させるのが目的であるので、コメントは一箇所につき一行に収めたい。
つまり、一箇所一箇所で細かな説明をするべきではない。あくまでそこでなにをしているのかが流し読みできるようにするのがコメントの目的だ。
*コメントだけで終わらせない
あくまでコード内のコメントは、あくまで主テーマ以外に本文解説を割かないための（解説を散漫にしないための）補足にすぎない。
本来の目的であったテーマについての解説は、本文側できちんと行うべきだ。
そもそもサンプルを登場させたのはあるテーマを説明するためのものだったはずなのだから、これを説明せずに、ただ「サンプルとそのコメントだけを見よ」というのは本末転倒である。
*コード内コメントはサンプル説明、本文説明は汎用的な解説
コード内コメントはサンプルそのものの説明、本文説明は汎用的な説明と、切り分けるのも一つの方法。
その記事が、サンプル集のような記事でない限り、サンプルはあくまでライブラリやキーワードを理解するための補足的な内容にすぎない。よって、サンプルの説明に終始するのは本末転倒。
最終的には、ライブラリやその機能を読者が理解して、「自分の」アプリケーションで応用できるまでを解説するのが目的であるはずだ。
*ポイントとなる部分は太字指定、積極的に（1）（2）の番号付けも
サンプルコードには、いかにシンプルとは言っても、多くの場合、本来のポイントとは関係ないコードはいくらでも含まれている。
その中で、著者がポイントと考えている部分をきちんとみせてやることは重要だ。
そのような箇所は太字指定にするのもありだと思うし、本文説明とリンクしているならば、できる限り、（1）（2）...のような番号付けをして、解説がサンプルコードのどの部分に対応しているのかを明確にしておきたい。
*番号は一行ごとに（細かく）振らない
リスト内に番号付けするのは重要な箇所にフォーカスして、本文で解説するのが目的。一行ごとに番号を振って、それを本文で解説するのでは重要箇所の説明が埋もれてしまうだけである。
＃しかも、結局、本文とリストとで目線を行き来させて文章を読み解かなければならないため、文章に集中できない。
先述したように、コードの大まかな流れはコード内のコメントで、本文解説はできるだけ汎用的な（重要部分の）解説に留めるのが望ましい。
*概要→サンプル→具体的な説明 が基本
最初に、コードの細かな流れや構文説明などを延々と進め、最後にまとめのようにサンプルコードを掲載している原稿を見かけるが、これはNG。
コードがまだ登場していない状態で、その内容を説明されても読み手は理解できない。
そもそもせっかく具体的なイメージを沸かせるために、サンプルを掲載しているはずなのに、サンプルがオマケのような位置づけになってしまっていて勿体ない。
サンプルを紹介する場合には、最初の説明は
-どんなサンプルを紹介しているのか
-その目的は？
-（場合によっては）実行結果のキャプチャ
程度の概要に留め、早い段階でサンプルコードを見せるべきである。具体的な、細かい説明はその後で良い。
*サンプルが長くなる場合
掲載すべきコードが極端に長い場合、必ずしも最初からすべてのコードを見せるべきではない。
その場合は、サンプルの構造が分かるような概念図やリスト、表を見せた上で、断片的なコードを順に抜粋していくという方法もあるだろう（最初に概念図、というのがキモ）。
＃もちろん、断片的なコードを紹介する場合にも、概要→コード→具体的な説明は基本である。
その上で、もし誌面が許すならば、最後にコード全体をまとめて見せても良い。もちろん、これは必須ではなく、断片的に見せたことでコード全体が把握しにくいと判断した場合のみ。
誌面が許さない、または読者がそれなりに中級者以上である場合には、「ダウンロードサンプルからコードを直接参照」とするのもあり。
*用例は意味ある単位で掲載
用例は、基本的にできるだけ短くが基本だ。しかし、意味ある単位で示すのが基本。目的の命令だけを示して、前後関係は読者が補足しないと分からないのではNG。
断片的であるにせよ、意味ある単位での紹介を心がけたい。
*サンプルではできるだけ日本語の例を
英語の方がなんとなくカッコ良かったりするので、英語で結果を出力したがる人は多い。しかし、多くの日本人にとっては日本語の方が視認しやすいはずだ。
また、見やすさだけではない。日本語（マルチバイト文字）を利用することで、文字化けにもきちんと対応したコードを紹介できる。サンプルの文字列を英語→日本語にしたら文字化けしてしまった、という質問は意外と多いので、要注意である。
*サンプルを収録 or ダウンロード提供している場合
サンプルは基本的にサーバ（ローカルマシン）に配置すれば、すぐに動作する状態にしておくのが望ましい。
そのままでは動作しない場合には、最低限、サンプルを動作するための手順を、記事内でも紹介しておくこと。
＃それが難しい場合には、Readme的なドキュメントを配布サンプルに収録しても構わない。
また、記事内のコードリストにも、かならず配布サンプル上のファイル名（必要に応じてパスも）を併記されたい。
記事の性質にもよるが、多くの場合、記事にコードのすべてを掲載することは稀だ。
読者が全体のコードを確認したいと思った場合にも、ファイル名を明記してあれば、参照は容易になる。
＃そしてもちろん、著者も気軽に?抜粋できるようになるだろう。
*一行あたりの長さはせいぜい60桁程度
書籍や記事のレイアウトにもよるが、1行あたりの桁数はおおよそ60桁程度。紙面上、折り返し記号を入れることもできるが、見やすさの観点からも、できるだけ利用は最小限にしたい。
また、折り返し箇所は機械的に決めるのではなく、意味ある個所で区切るべき。
*変数名やデータベースのフィールド名、XMLの要素名などは英語表記で
これは状況によって変わるかもしれないが、少なくとも日本語の変数名は避けるべき、だと思う。
**************途中*********
サンプルの取捨選択や説明の仕方について。
*サンプルの選択の仕方
サンプル作成の基準は以下。
+最大限、シンプルであるか
+対象となる命令の使いどころを理解させるのに十分であるか
サンプルは凝ったものである必要はない。しかし、ただ構文をただなぞっただけでは意味がない。
構文を理解させるのは最低限、その上で、その機能がどのような局面で利用されるべきものかが実感できるようなサンプルが好ましい。
もっとも、それでサンプルが複雑なものになってしまうのは、それはそれで好ましくない。1.のルールを維持するためにも、ある程度は文章で「使いどころ」を補うことを検討する必要があるだろう。
*基本的にはすべての説明に何らかのサンプルがあるべき
記事の中で説明しているキーワードや概念、機能について、ただ説明だけで終わり、というのは原則不可。
どんなに分かりやすい解説であっても、読者が理解するうえで、実際のサンプルコードに勝る手掛かりはないからだ。
ひとつのキーワードや機能について、サンプルはかならずひとつ以上。
*基本的にはすべてのサンプルに何らかの説明があるべき
前項と逆の話。どんなに解りやすいサンプルでもただコードだけを載せて、説明はなしというのは不可。なにかしら説明をするためのサンプルであるはずなので、説明が不要なサンプルというのはありえない。
＃ただし、本題から外れる部分は別。JavaScriptでAjaxの説明をするのに、サーバサイドのコードについて説明を省略するのはあり。
ましてや、サンプルをダウンロードだけさせて、「説明はないけどあとはソースを見てね」というのは避けるべき。見てくれる読者はおそらくほんの一握りと思われ、そんな無駄な労力をかける必要はない。
*サンプルには必ず実行結果も掲載
コードだけを見よ、では不十分。サンプルではその結果を見せることで初めて、読者がイメージを持つことができる場合も多い。
結果のあるサンプルで結果をきちんと掲載するのはもちろん、結果のないサンプルもできるだけ結果が見えるような形にするべきである。
たとえば、クラスの説明ならば、単にクラスを定義するだけでなく、クラスをインスタンス化し、呼び出すコードまでが望ましい。
＃もちろん、説明の方法によっては、クラスの定義と呼び出しの説明は別々にした方が良いこともあるかもしれない。
コマンドなどを見せる場合も同様。結果を見せることで、読者はその結果が等しいことで安心しながら、手元の作業を進められる。
*実行結果が環境などの要因で異なる場合
必ずその旨を明記すべき。特に初学者向けの記事の場合は、実行結果が手元で試した時と違うと、読者が混乱したり不安に陥ったりする原因にもなる。
個別に記載するのが冗長である場合には、書籍では「本書の読み方」などで、個別記事の場合は記事先頭などで、フォローするのもありだろう。
*コメントはできるだけ細かく加えること
対象読者にもよるが、少なくとも入門者向けの記事であれば、コメントを読んでいくだけでも最低限、コードの流れが追える程度のコメントを加えておくのが望ましい（もちろん、一行一行にコメントが必要、という意味ではない）。
あくまで流れをざっと理解させるのが目的であるので、コメントは一箇所につき一行に収めたい。
つまり、一箇所一箇所で細かな説明をするべきではない。あくまでそこでなにをしているのかが流し読みできるようにするのがコメントの目的だ。
*コメントだけで終わらせない
あくまでコード内のコメントは、あくまで主テーマ以外に本文解説を割かないための（解説を散漫にしないための）補足にすぎない。
本来の目的であったテーマについての解説は、本文側できちんと行うべきだ。
そもそもサンプルを登場させたのはあるテーマを説明するためのものだったはずなのだから、これを説明せずに、ただ「サンプルとそのコメントだけを見よ」というのは本末転倒である。
*コード内コメントはサンプル説明、本文説明は汎用的な解説
コード内コメントはサンプルそのものの説明、本文説明は汎用的な説明と、切り分けるのも一つの方法。
その記事が、サンプル集のような記事でない限り、サンプルはあくまでライブラリやキーワードを理解するための補足的な内容にすぎない。よって、サンプルの説明に終始するのは本末転倒。
最終的には、ライブラリやその機能を読者が理解して、「自分の」アプリケーションで応用できるまでを解説するのが目的であるはずだ。
*ポイントとなる部分は太字指定、積極的に（1）（2）の番号付けも
サンプルコードには、いかにシンプルとは言っても、多くの場合、本来のポイントとは関係ないコードはいくらでも含まれている。
その中で、著者がポイントと考えている部分をきちんとみせてやることは重要だ。
そのような箇所は太字指定にするのもありだと思うし、本文説明とリンクしているならば、できる限り、（1）（2）...のような番号付けをして、解説がサンプルコードのどの部分に対応しているのかを明確にしておきたい。
*番号は一行ごとに（細かく）振らない
リスト内に番号付けするのは重要な箇所にフォーカスして、本文で解説するのが目的。一行ごとに番号を振って、それを本文で解説するのでは重要箇所の説明が埋もれてしまうだけである。
＃しかも、結局、本文とリストとで目線を行き来させて文章を読み解かなければならないため、文章に集中できない。
先述したように、コードの大まかな流れはコード内のコメントで、本文解説はできるだけ汎用的な（重要部分の）解説に留めるのが望ましい。
*概要→サンプル→具体的な説明 が基本
最初に、コードの細かな流れや構文説明などを延々と進め、最後にまとめのようにサンプルコードを掲載している原稿を見かけるが、これはNG。
コードがまだ登場していない状態で、その内容を説明されても読み手は理解できない。
そもそもせっかく具体的なイメージを沸かせるために、サンプルを掲載しているはずなのに、サンプルがオマケのような位置づけになってしまっていて勿体ない。
サンプルを紹介する場合には、最初の説明は
-どんなサンプルを紹介しているのか
-その目的は？
-（場合によっては）実行結果のキャプチャ
程度の概要に留め、早い段階でサンプルコードを見せるべきである。具体的な、細かい説明はその後で良い。
*サンプルが長くなる場合
掲載すべきコードが極端に長い場合、必ずしも最初からすべてのコードを見せるべきではない。
その場合は、サンプルの構造が分かるような概念図やリスト、表を見せた上で、断片的なコードを順に抜粋していくという方法もあるだろう（最初に概念図、というのがキモ）。
＃もちろん、断片的なコードを紹介する場合にも、概要→コード→具体的な説明は基本である。
その上で、もし誌面が許すならば、最後にコード全体をまとめて見せても良い。もちろん、これは必須ではなく、断片的に見せたことでコード全体が把握しにくいと判断した場合のみ。
誌面が許さない、または読者がそれなりに中級者以上である場合には、「ダウンロードサンプルからコードを直接参照」とするのもあり。
*用例は意味ある単位で掲載
用例は、基本的にできるだけ短くが基本だ。しかし、意味ある単位で示すのが基本。目的の命令だけを示して、前後関係は読者が補足しないと分からないのではNG。
断片的であるにせよ、意味ある単位での紹介を心がけたい。
*サンプルではできるだけ日本語の例を
英語の方がなんとなくカッコ良かったりするので、英語で結果を出力したがる人は多い。しかし、多くの日本人にとっては日本語の方が視認しやすいはずだ。
また、見やすさだけではない。日本語（マルチバイト文字）を利用することで、文字化けにもきちんと対応したコードを紹介できる。サンプルの文字列を英語→日本語にしたら文字化けしてしまった、という質問は意外と多いので、要注意である。
*サンプルを収録 or ダウンロード提供している場合
サンプルは基本的にサーバ（ローカルマシン）に配置すれば、すぐに動作する状態にしておくのが望ましい。
そのままでは動作しない場合には、最低限、サンプルを動作するための手順を、記事内でも紹介しておくこと。
＃それが難しい場合には、Readme的なドキュメントを配布サンプルに収録しても構わない。
また、記事内のコードリストにも、かならず配布サンプル上のファイル名（必要に応じてパスも）を併記されたい。
記事の性質にもよるが、多くの場合、記事にコードのすべてを掲載することは稀だ。
読者が全体のコードを確認したいと思った場合にも、ファイル名を明記してあれば、参照は容易になる。
＃そしてもちろん、著者も気軽に?抜粋できるようになるだろう。
*一行あたりの長さはせいぜい60桁程度
書籍や記事のレイアウトにもよるが、1行あたりの桁数はおおよそ60桁程度。紙面上、折り返し記号を入れることもできるが、見やすさの観点からも、できるだけ利用は最小限にしたい。
また、折り返し箇所は機械的に決めるのではなく、意味ある個所で区切るべき。
*変数名やデータベースのフィールド名、XMLの要素名などは英語表記で
これは状況によって変わるかもしれないが、少なくとも日本語の変数名は避けるべき、だと思う。
**************途中*********
