[go: up one dir, main page]
More Web Proxy on the site http://driver.im/

$shibayu36->blog;

クラスター株式会社のソフトウェアエンジニアです。エンジニアリングや読書などについて書いています。

開発のドキュメントをどこに置くか問題

tech

　最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば

  • 開発環境セットアップ方法
  • ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた)
  • サービス内の特定の機能の仕組み
  • 内部用HTTP APIドキュメント

などを指している。


　結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと

  • 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う
  • いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く
    • 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う

　あといろいろ悩んでるので事例あったら教えてください。

起きている問題

　ドキュメントはそれなりに人が変わりうるプロジェクトでは必須だと個人的には思っている。とはいえ

  • ドキュメントがあるのに見つけてもらえない
  • ドキュメントはあるのに実装に追従できてない

などといった問題も頻繁に起こる。

　ドキュメントがあるのに見つけてもらえない原因としては

  • 検索しづらいところにある
  • そもそもあることに気づいてない

とか。

　ドキュメントはあるのに実装に追従できてない原因としては

  • 編集しづらい
  • いつものフロー(例えばpull request)に載ってない
  • そもそもあることに気づいてない

とか。


　最近いろいろ考えたけど、なんとなくは

  • 出来るだけコードのコメントとして実装に近いところで完結させる
  • いろんなコードが集合して一つの機能になっている時は、最初の導入部分だけドキュメントを書く
    • 1つのrepositoryである程度完結するならrepositoryに入れる
    • いろんなrepositoryにまたがってしまうなら仕方なくグループウェアに書く
  • エンジニア以外も見るような場合は、それ以外の人が見る部分だけグループウェアに書いて、repositoryのドキュメントと相互参照する

というのをやってる。

出来るだけコードのコメントとして実装に近いところで完結させる

　基本は実装の近くにあるコメントとして完結させる。内容が局所的かつそのrepositoryを扱う人しか見ないんだったら、出来るだけ実装に近い部分にコメントとしてドキュメントを残したほうが見つけやすさ・更新しやすさが高い状態に保てると思う。

　一番上の例で言えば「サービス内の特定の機能の仕組み」の中の、それぞれのパーツの動きやそのパーツの他との関わりというあたり。あと最近だと内部用HTTP APIドキュメントはテストとして作成して自動生成するとかもある。

　例を挙げると

  • ルーティングどう書くか・それぞれどうdispatchされるかという部分はルーティングをしてるファイルにコメントで書く
  • 特定のnginx設定が他のファイルをincludeしてるとき、その二つの関係をコメントで書く

いろんなコードが集合して一つの機能になっている時

　まず機能のバグフィックスとか機能追加とかしたいとき、かつその機能が結構大きい場合はいろんなコードが協調して動くようになっている。こういう時は

  • そもそもどこから見たらいいかわからない
  • 全体像がなんとなく把握できないとコードだけではそれぞれがどう絡んでるか分からない

などのことが起こる。


　なので最近はこういう時で、かつrepositoryである程度完結する場合は、最初の導入部分(全体のクラスの関わりとか、データの流れとか)は、出来るだけ図を使ってドキュメントを書く。さらにそれをmarkdownか何かでrepositoryの特定のディレクトリに配置しておくというふうにしてる。

　一番上の例で言えば「サービス内の特定の機能の仕組み」でその機能が結構大きい機能の場合。とにかく図を増やして機能の仕組みを俯瞰でき、コードリーディングを始められる状態まですぐに行けるように気をつけてる。出来るだけ詳細は書かない。

　もちろんこの時見つけやすさ・更新しやすさは実装の近くに配置したコメントより損なわれている。けれどそもそも何もわからない人はどこが関連するコードなのかとか、コードリーディングあたって必要な概観みたいなのが分からないと、コメントすら見つけられないよなと思ってこういうふうにしてる。またrepositoryに入れることで実装のpull reqにドキュメントの変更を入れることが出来、ある程度は更新しやすさも担保できるかなという感じ。


　とは言え複数のrepositoryがそれぞれ同程度関わりあって機能が出来ている場合は、repositoryに入れると見つけにくいので、仕方なくグループウェアに書いたりしてる。この場合も導入部分や各repositoryがそれぞれ何を担当しているかくらいに留めて、詳細は書かない。

エンジニア以外も見るような場合

　こういう場合はrepositoryの中に入れたら見えない人が出てくるので、更新しやすさを捨てて、だれでも見えるグループウェア上においてる。とはいえこの時も他の人が見る部分だけグループウェアに書いて、エンジニアだけが見たらいい部分はrepositoryに入れたりしてる。それで相互リンクさせる。

　上の例では「ページに表示している広告をどのように切り替えたりするか」という部分で、google内でなんかするやつはグループウェアに書いて、コード上の変更が必要な部分はrepositoryに入れたりコメント書いたりする。

まとめ

　結構抽象的になってしまった。基本は実装に一番近いところにコメントとしてドキュメント書くのが良くて、とはいえ導入ないと分からないよなという部分には俯瞰できるように図とか置いておきたいという感じです。

　あと全然つながりはないけど、最近ドキュメント書く時はオブジェクト指向の隠蔽の話を思い出してて、出来るだけ関係のない人には情報を見えないようにしつつ、関係があるときにすぐ見つけられるみたいな感じにしてるのかもしれない。