Makefileを自己文書化する | POSTD
私たちのプロジェクトではいつも、非常に長い Makefile を使用して、インストールやビルド、テスト、デプロイメントの処理を自動化しています。ターゲット名はほとんど標準化されていますが（ make install 、 make deploy ）、中には説明が必要なものもあります（ make run-dev 、 make restart-api ）。そして、詳細なmakeターゲットを追加するほど、それらの処理内容をテキスト形式で大量に記載しなければなりません。私たちのプロジェクトでは通常、このような文書を README ファイルに書いています。 しかしCLI（コマンドラインインタフェース）を用いる場合は、主に自己文書化ツールを使っています。 make と打つだけで、利用可能なコマンドとその説明が一覧表示されたら便利だと思いませんか？ それを実現するのは、実はとても簡単です。まずは各ターゲッ
ドキュメントの場所を知らせるために、落ちるテストを作る - $shibayu36->blog;
今回はドキュメントの場所をどうやって気づかせるかという話を書く。 ドキュメントがあるときの問題 以前開発のドキュメントをどこに置くか問題 - $shibayu36->blog;に書いたとおり、僕の意見としては 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う というものだった。 基本的には一番近いコメントにすると、見つけやすさ・更新しやすさともにある程度担保することが出来る。しかし、メインの部分が明確に決まらない*1いろんなパーツが関係しあう機能の場合は、ドキュメントを書かないと全体の概要が分からないということもある。このような時、ドキュメントを書いても結局そのドキュメントに気づかれないし、そのため更新されないとい
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
