普段記事を書くときに心に思っていることを文字に起こしてみる。
思っているだけで、実践できているかどうかは怪しい。けど、心がけようとはしている。
あと、個人的な経験と感覚に依る考えなので、正しさは保証できません。
当方、ライブラリの使い方とかが多いので、それ以外の記事には当てはまらないものもあると思います。
インストール方法を載せる
ライブラリやツールの使い方について書く場合は、そのインストール方法を載せるようにしてます。
Java ライブラリの場合は Gradle などの依存関係を管理するツールを使っている前提で、最低でもその設定を載せるようにしています。
ライブラリでもツールでもそうですが、まずインストールできないとやる気が完全に失せて萎えます。
第一歩を踏み出せるようにするためにも、インストールの方法は書いておいたほうが良いと思ってます。
Hello World を載せる
兎にも角にも、まず動くところが見れないとやる気が完全に失せて萎えます。
ややこしい話は全て無しにして、とりあえずまずは最小限のコード（設定）で動くものが見れた方が良いと思ってます。
Hello World で、そのライブラリがどういうものなのか分かるようにする
「このライブラリって結局何ができるものなの？」が分からないと、やる気が完全に失せて萎えます。
Hello World は、「あぁ、このライブラリってこういうものなのね」が分かるようなものだと良いと思ってます。
サンプルコードを必要最小限にする
サンプルコードに知りたいこと以外の情報が載っていると、そのことを理解するのに脳のリソースが奪われるため、理解の妨げ（ノイズ）になると思ってます。
User user1 = new User("Sato", 16);
User user2 = new User("Suzuki", 17);
List<User> users = Arrays.asList(user1, user2);
int sum = 0;
users.forEach(user -> {
sum += SomeLibrary.add(some, user.getAge());
});
System.out.println("sum=" + sum);
かなり極端な例ですが。。。
例えば、上記のコードが、実は SomeLibrary.add(int, int) の使い方を説明することが目的だとします。
知りたいのは add() 関数の使い方だけなので、それ以外のコードはノイズになります（User クラスが名前と年齢を持つ、とかいう仕様は add() 関数の理解に何の関係もありません）。
この場合、以下のようなサンプルコードで十分だと思います。
System.out.println(SomeLibrary.add(1, 2));
サンプルコードに「具体的な意味」を持たせない
ライブラリなどの使い方を説明しようとすると、ついつい「具体的な使用例」みたいなのを書いたほうが分かりやすそうと思ってしまいます。
しかし、それをすると前述のようなノイズが多く発生します。
それよりかは、とにかくシンプルに、必要最小限だけのコードで済むようにしたほうが分かりやすいと、個人的に思ってます。
なぜなら、コードに「具体的な意味」を持たせないほうが API などの本質的な挙動が見やすくなり、本来知りたいこと（API の使い方など）の理解に集中できると思うからです。
なので、変数名なども極力 hoge や fuga のような「意味のない名前」を使うようにしてます。
サンプルコードに実行結果を載せる
自分の経験上、ライブラリの使い方などが知識として定着したと実感するときというのは、コードの実行結果が自分の予想と一致したときだと思っています。
つまり、
- 試しにコードを書く。
- 動作結果を予想する。
- コードを動かす。
- 実際の結果と、自分の予想を照らし合わせる。
として、照らし合わせた結果が同じだと「自分の理解が正しかった」ことが分かり、確かな知識として定着するのを実感できます。
実行結果を見ないと、いつまでたっても「予想」は「予想」のままで、知識として定着しません。
そもそも、「予想」が間違っていることもあるので、答え合わせとして実行結果を確認することは必須です。
サンプルコードに実行結果を載せることは、この体験と同じ効果があると思います。
つまり、
- サンプルコードを見る。
- 動作結果を予想する。
- 記載されているサンプルコードの実行結果と、自分の予想を照らし合わせる。
記載されている実行結果と自分の予想が等しいと、その理解は知識として定着します。
究極は、サンプルコードと実行結果だけ見れば、説明文無しでも API の使い方が分かるようなものになれば、それが最も良い状態だと考えています。
サンプルコードを省略しない
サンプルコードからは、極力ノイズを除去した方がいい。
しかし、それは単純に文字数を減らせば良いという意味ではない。
サンプルコードは、極力省略しないほうが良いと思う。
よく見るのが、変数やメソッドの宣言の省略。
これをされると、「あれ？ この変数（メソッド）って突然現れたけどなんだろう？」と疑問符が浮かんでしまいます。
これは思考の中断に繋がり理解の妨げになるため、ノイズの一種だと考えてます。
しかし、変数やメソッドの宣言を全て載せていると、サンプルコードはどんどん大きくなっていく。
それはそれで、理解の妨げにつながりノイズに発展してしまう。
省略せず長くなり過ぎないようにする。
これらを両立するには、結局のところコードに「具体的な意味」を持たせないことと、「必要最小限」になるようにサンプルを考えることに繋がると思う。
サンプルコードは適度に省略する
省略しないと言っても、さすがに同じコードを何度も載せるのは邪魔だと思う。
なので、既に記載済みのクラスや、今説明していることと直接関係がない部分のコードは省略したほうが良いと思う。
import 文を省略しない
import 文を省略されると、サンプルコード中に登場した型が「ライブラリが提供している型」なのか、「筆者が独自に作った型」なのかが分からなくなることがある。
（たまに、ライブラリが提供しているクラスかと思ってたら、筆者が作った独自クラスだった、ということがあったりする）。
手元に Eclipse のような IDE があれば確認もわりと簡単にできるが、ネット上の記事は電車の中でスマホとかを使って見ることもあるので、できれば簡単に分かるようになっていた方がいい。
ということで、 import 文は省略しないようにしている。
しかし、 IOException とか ArrayList のようなあまりにも自明なクラスについては、省略しても良いかなとは思っている。
これらは、逆に記載されていたほうがノイズになるかもしれない。。。
これも、 import 文を省略せず、しかし多くなり過ぎないように最小限にする必要がある。
そのためには「具体的な意味を持たせない」ことと「必要最小限」の考えに、結局のところ繋がっていくと思う。
サンプルコード上にコメントで説明を載せる
これは、最近意識するようになってきた。
最初はコードと説明を別々に書いていた。
しかし、そうするとどうしてもコードと説明が離れたところにあるため、目線の移動が発生してしまう。
これはこれで理解の妨げに感じるので、最近はコード上にコメントで説明を載せるようにしている。
しかし、コメントを書きすぎると、それはそれでノイズになるので、なるべく最小限に抑えるようにしている。
また、どうしてもサンプルコードが長くなってしまったときは、「特にどこに着目すべきか」を分かりやすくするために、印代わりのコメントを書いたりしている。
試行錯誤中。。。
説明していない言葉を使わない
初めて使う用語などを、説明なしで使わないようにしている。
文中で頻繁に使うことになる用語は、先に説明を載せてから使う。
どうしても後で説明したほうが分かりやすいと判断した場合は、（詳細後述）みたいな注記を載せるようにしている。
読む人が上から順番に読むという保証はないけど、そこはどうしようもないので、勝手に前提にしている。
（説明箇所へのリンクを置く方法もあるかもしれないけど、さすがに面倒すぎる。。。）
読みなおす
一度書いた文章は、必ず一度は読みなおす。
たいてい、誤字脱字が一箇所以上ある。
また、時間をあけて読むと、意味が伝わりにくい文章・読みにくい文章・日本語としておかしい文章の存在に気づくことができる。
さっさと投稿したくなる気持ちを抑えて、とりあえず一度は読みなおすようにしている。
（でも、結局投稿後に誤字に気づいて、慌てて修正したりしてる。。。）
一文を短くする
読みやすい文章の指南書とかを読むと、必ずと言っていいほど書いてある手法。
それが、一文を短くする、という方法。
一つの文は、一つのことだけを書く。一つの文に二つ以上のことが書かれていると、読む側は理解するのが難しくなる。
例えば、一つの文中に読点が４つくらい現れて、「～が、」や「～で、」などで繋がっている文章は、一つの文章に二つ以上の内容が詰め込まれている合図であり、読み手としては最初に読んでいた内容を記憶することができず、最後まで読んでも結局また「あれ、最初の方はなんて書いてたっけ？」と最初に戻ることになり、それよりは、一つ一つの文を短くし、一つの文で一つの内容だけを含めるようにしたほうが良い。
↓ 修正
例えば、次のような文は赤信号と思ったほうが良い。
- 一つの文中に読点が４つくらい現れる。
- 「～が、」や「～で、」などの文言で文が繋がっている。
一つの文に複数の内容が詰め込まれていても、読み手はそれを読みながら記憶しておくことができない。
たいてい、最後まで読んでから「あれ、最初の方はなんて書いてたっけ？」となってしまう。
それよりは、一文を短くし、一つの文で一つの内容だけを含めるようにしたほうが良い。
また、箇条書きや段落分けも、見やすい文章を書くために重要な手法といえる。
さいごに
文字に起こして分かったことは、自分がいかに「サンプルコード」に重きをおいているか、です。
思いの外、「サンプルコード」への意識が強いみたいです。
実際、サンプルコードがわかりやすければ、説明文が英語だろうかロシア語だろうがチョミメン語だろうが理解できますからね。
プログラミング言語はプログラマーの世界共通言語です。
そんなプログラミング言語で意図を伝えられるサンプルコードは、重要なものなのだと思います。