成果物の全ての箇所に根拠を持たせる

成果物の全てに対して、根拠を説明できるようにしておく。

「なぜそのファイル名にしたか」「なぜそこにスペースを入れたのか」「なぜこの手法を採用したのか」「どうしてこのやり方は選ばなかったのか」。成果物のどのポイントにも根拠を示せるようにするのが、成果物責任であろう。

• 「何となく」で見栄えを作らない
  • 「見出し」を表現するために、「適当に」文字サイズを大きくし、「何となく」黒丸記号 ● を使って目立たせたりしない
  • そのドキュメントにおける「見出し」のマークアップを適切に行い (HTML や Word は「見出し」を定義できる)、その上で統一感のある見出しスタイルにするべき
  • ドキュメントのテンプレートがあるのであれば、そのテンプレートに従い、独自のスタイリングをしたりしない
• 「とりあえず動いているから OK」ではない
  • 「どうしてこのように実装すると動くのか、説明はできないが、色々なサイトからコピペしていたら上手くいった」といったレベルのコードは顧客に提供できない。カーゴ・カルト・プログラミング (おまじない) の可能性が高い
    • 関連ブログ記事 : 2017-09-23 カーゴ・カルト・プログラミング
  • 他にも同様の結果が得られる実装方法があることを理解しているか、それらを比較してその場に最適な手法を選択したか、説明できないといけない
  • 何らかの理由でセオリーから外れた実装になっているのであれば、コメント等で「セオリーどおりの実装をした場合の弊害」「この実装に落ち着いた経緯」などを根拠として残しておく。根拠が分からないコードは後で「リファクタリング」されてしまうかもしれない
• 「前例がこうだったから真似した」だけでは理由にならない
  • 「前にもこうだったから」は、「今回もこうする」という理由にはならない。それぞれの前例に対して、どういう理由でその手法を選んでいたのか、理解を深めておかないといけない
  • 往々にして、前回も、何も考えずに過去の事例を真似していただけだったりする。カーゴ・カルトを引き継ぐのは止めて、毎回ゼロベースで根拠を考える
  • 関連ブログ記事 : 2017-11-25 「前例がそうだったから」だけでは根拠にならない
• 根拠は正確に文書化する
  • 参考にした実装方法を URL 付きでコメントに残す
  • あるドキュメントを作成するにあたって参照したデータ等があれば、その書籍、URL を書き残す
  • 「誰かがそう言っていたと思う」という記憶ベースでは根拠として乏しいので、議事録は必須。口頭でやり取りした内容はメール等で文書化して相手と認識相違がないか確認する

残念ながら、他の人達が常に根拠を考えながら仕事しているワケではない。中身を理解もせず、影響や負債を考えもせず、「よく知らないけど何となく毎回コピペして使っている」といったエンジニアは多い。

彼らを真似していても、良い効果は得られない。自分が作るモノには責任をもって、根拠を示そう。