コグノスケ

残念なコメント

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

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

//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つ目、コードのコメントです。

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

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