コグノスケ

電線に掛かる電圧

切れた電線に絶対に近寄るな（参考: 東京電力のサイト）、という注意文を初めて見たのは、確か小学生だったと思うのですが、当時は電線の電圧が100ボルトだと勘違いしていたので、切れた電線が何故そんなに危険なのかよく分かって居ませんでした。

しかし高校か大学だったか、実は、その辺の電信柱を通っている電線の電圧は6600ボルトだと知って戦慄を覚えました…。

メモ: 技術系の話はFacebookから転記しておくことにした。

継承と委譲

今日、初めて 〜Java 7の単一継承でつまづきました。

Javaなら継承じゃなくて、委譲だろ？という天の声が聞こえますが、委譲先と同じ名前の関数が増えてうっとおしいです。継承の方がスマートだと思うんだけどなあ…。

このまま委譲で作るか、思い切ってJava 8のMix-in機能に変えるか、悩ましい。

メモ: 技術系の話はFacebookから転記しておくことにした。

残念なコメント

コードのコメントは有った方が嬉しいですが、有ればいいってもんでもないです。

たとえば…、下記のような「見たら分かるわ！このおバカ！」というレベルのコメントは、いくら有っても嬉しくありません。

//hogeの合計を出す
for (i = 0; i < hoge_length; i++) {
    sum += hoge[i];
}

こんなコメントより、合計を何に使うのか？どうして今計算するのか？のコメントの方が嬉しいですよね。

しかし会社のコードでは、ひどいレベルのコメントを良く見かけるので、残念極まりないです。仮にもソフト開発部門なのに、こんな体たらくで良いのか……？

メモ: 技術系の話はFacebookから転記しておくことにした。

おー人事、おー人事

最近、職場から人が去っていくことが多く寂しい限りです。

人が去るとき、残った人にコードを引き継ぎますが、大抵の場合、さほど詳しくない人がコードを引き継ぐことになります。

詳しくない人が、引き継いだコードを使おう、変えよう、とするのは非常に大変です。自身の経験でも、周りの人を見ていても、そう思います。

さほど詳しくないコードを引き継ぐときに、この情報があれば良かった…と思うことが2つあったので、自分が何か作るときの戒めとして書いておきます。

あったら良かった2つのこと

• 1つ目は初心者のための「使い方」
• 2つ目は熟練者のための「なぜその方法を取ったか」

「使い方」は、初めての人でも数分〜1時間で使い方がわかると嬉しいですね。

引き継いだのに初心者ってことは無いだろう？と思われるかもしれませんが、残念ながら、実際のところ初心者のことが多いです。断片的な設計資料があればマシな方ですが、初心者には全く役に立たない場合が多いです。

「なぜその方法を取ったか」は、コードを読んでも見えてこない設計の「Why」が書いてあると嬉しいですね。

文章の5W1Hと同じように、コードにも「When」「Where」「Who」「What」「How」が書かれています。余程クソみたいなコードじゃない限り、仮に設計資料が全く無かったとしても、コードを読んだり、動かしながら解析すれば5W1Hまでは何とかなりますが、「Why」は絶対にわかりません。

例えば、問題Qがあって、方式Aと方式Bという解決方法があったとします。コードを読んだり解析すれば、Qを解決しようとしていること、Aを採用していること、まではわかります。しかし、なぜAを採用したか？は、いくらコードを見てもわからないのです。

設計の「Why」にこだわる理由は、設計を変更する（例えば方式Aを方式Bに変える）時に、非常に重要な情報となるからです。

単に方式Aしか知らなかっただけなら、方式Bへの置き換えは検討に値するでしょう。でもBは地雷で別の問題を誘発するなら、Bは地雷だと書いておけば後継者が無駄な検討をせずに済むはずです。

情報を残す場所

自身の経験から言って、コードのなるべく近くに「使い方」と「なぜその方法を取ったか」があると嬉しいです。情報を残す手段として良く見かけるのは4つです。

1つ目、WikiやTracなどのWebシステムです。

• まとめて書ける、読みやすいのが利点
• コードとの対応が取りづらいのが欠点

特に「使い方」を書くとき、多人数に公開する情報を書くときに向いていると思います。コードと一緒にはできないので、コードとの対応を書いておくと良いと思います。

2つ目、PowerPointのスライドです。会社では一番多く見かけます。

• 図が書きやすいのが利点
• 差分が追いづらい、コードとの対応が取りづらいのが欠点

コードとバラバラに管理すると散逸しやすいのでPowerPointで情報を残したいなら、コードと一緒にコミットすると良いと思います。

3つ目、READMEのようなテキストです。

• 差分が追いやすく、まとめて書けるのが利点
• 長くなると読みづらく、コードとの対応が取りづらいのが欠点

コードのトップディレクトリに置いておくと目立つので「使い方」を書くときに向いていると思います。コードと一緒にコミットするのが普通でしょう。

4つ目、コードのコメントです。

• 差分が追いやすく、コードとの対応が取りやすいのが利点
• まとまりがなくなるのが欠点

必ずコードの近くに書けるので「なぜその方法を取ったか」を書くときに向いていると思います。コードと一緒にコミットされる（そうせざるを得ない）のも良いですね。