読者です 読者をやめる 読者になる 読者になる

筋肉とエンジニアリングで すべてを解決するブログ

筋トレ、JavaScript、Ruby で世界を変えてやります。

ドキュメントを常に残し続けることが大切な3つの理由

ドキュメント書かない人ってすごい多くて、本質的な部分じゃないから軽視されがちなんですよね。

僕的には、テストを書かないくらい軽視しちゃいけないものだと思ってます。

で、最近無駄だなーと思うことの一つが、ドキュメントを残さずに開発し続けることだと思っています。

大きな理由は3つ。

  • コードを書いた人に質問する回数が増える
  • コードをいちいち読む時間が無駄
  • 自分の思考の整理ができない

賛否両論あるかと思いますが、僕の考えてる理由について解説したいと思います。

コードを書いた人に質問する回数が増える

僕がドキュメントを残してもらいたい理由のうち大きなウェイトを占めるのがこれ。

よくわからないコードが入っていたりすると、どうしてそこにそれを入れなきゃいけないのか、とかコードベースで自分で改めて考えなおさなきゃいけなくて超面倒。

で、考えてもわからないものを直接聞くと、自分と相手の時間が奪われてしまう。

これが自分一人だったらまだなんとかなるかもしれないけど、同様にわからなくて質問する人が自分以外にも居たとしたら説明するコストとかがかかる。

効率、自動化を求めるのがエンジニアだと思うけど、ドキュメントにもコストを割くことで説明の回数も少なくなると思う。

特に、一般的に使われそうなコードだとか、今後も手を加えそうなコードだと思ったら必ずドキュメントを残すべき。

コードをいちいち読む時間が無駄

コードを読むのって勉強になるんですが、読む時間が無い時とか、読みたくないようなすさまじいコードを読まなきゃいけない時の苦痛は僕はあんまり好きじゃないです。

時間があるときにソースコードリーディングすればいいと思うし、コード書いてみて動かなかったりした時に初めて見るくらいで十分なんじゃないかなぁともよく思います。

単純にトライアンドエラーを繰り返した後に得られた知見だとか、同じように時間を使わない ようにするための工夫ってのを盛り込んだドキュメントを作ることで、無駄な時間を減らせるんじゃないかなぁと思っています。

自分の思考の整理ができない

自分が作りたいものを作るためだったり、自分がしたい作業をするには何かしら整理してから実行していくことが必要だと思います。

コードを書く前に設計書を書いてある程度抜け漏れがないかチェックする。自分が行う作業は後戻りがしにくい作業だったりした場合に安全に作業が行えるように実行順序をまとめておく。

こういった行為のログをまとめていかないと、他者からレビューを受けにくいとか、今後同じ思想を持った作業をするときに抜け漏れが出てきたりしまうのが問題です。

思考をまとめたログを残すことでこれを防ぐ事ができると思います。

まとめ

僕が書いた内容は当たり前のことかもしれませんが、ドキュメントを残さない人が多いと、後々誰かしらが困る状態が容易に想像できます。

面倒だから、時間がないから、自分しか使わないから、なんて思ってると、あとで余計面倒になったり、時間の効率がだんだん悪くなり、依存性が高くなり、と悪いことだらけになります。

チームプレイでの開発なら尚更、相手を思ってドキュメントを残していくことで全体最適化になるんじゃないかなと思います。

是非ともドキュメントを書くことを軽視してる方はドキュメントの重要性についてみなおしてみて欲しいです。