2005年05月17日

Code Reading 第8章: Documentation

この章は8.2以外は短い。

8.1 Documentation Types

プロジェクトに関する文書をおおまかに5種類に分類。

the system specification document
システムの目的、機能要求、管理・技術的制約など。
→コードの動作する環境についての知識が得られる
the software requirements specification:
ユーザ要求の高レベルな記述、システム全体のアーキテクチャ、処理や外部インタフェース等の要求の詳細。
→コードを読んだり評価するベンチマークとなる
the design specification
システムのアーキテクチャ、モジュール間のインタフェースやデータやコードの構造など。
→コードの構造のロードマップ、特定のコードを読むときのガイドに。
system's test specification
テスト計画、テスト手続き、テスト結果等。
→コードのdry-run(机上での検討)をデータつきで提供してくれる
user documentation
機能の説明、インストール手順、その他もろもろ
→対象がどういうシステムなのか知らねば始まらない。

8.2 Reading Documentation

ソースコードを読む参考情報を文書から読み取る様々な例。

  • コードから動作を読み取るよりも文書から情報を得た方が理解が早い例: catの改行コードの処理のループ(manの-sオプションの説明を読む方が早い)。
  • 文書のセクションとソースファイルとがかなり対応(例: sendmail)。
  • 複雑なアルゴリズムは難解なコードよりも文章による説明の方がわかりやすいことも。 文書の情報により、識別子の名前からそれが意味するものを把握しやすくなる。l
  • デザイナーの思考や検討された対案などを読めることもある(例: Plan 9)。
  • システムの内部APIの説明文書(hsqldb/dev-docs/hsqldb/index.html, perl/perlguts.pod, FreeBSDやNetBSDのmbuf(9)をはじめとするmanのセクション9)。
  • テストケースや利用例(tcpdump(8))。
  • 実装上の問題、caveats(機能が働かない可能性の警告)、バグ。
  • OSやコンパイラのバグなど環境上の理由による問題とその対処→ソース上のコメントがほとんど。

8.3 Documentation Problem

文書は常に正しい情報を与えてくれるとは限らない。

  • 様々な理由により、実装された機能が文書化を避けられることもある
  • 文書が、システムは「どのように実装されているか」でなく「どのように実装されるべきか」を述べている可能性
  • コードの進化にドキュメントが追随しなかった場合

8.4 Additional Documentation Sources

ほかにもnon-traditionalな幅広い情報が得られる。comments, standards, publications, test cases, mailing lists, newsgroups, revesion logs, issue-tracking databases, marketing material, and the source code itself.

コメントは実行されるわけじゃないので正しいとは限らない。 標準を実装しているならその標準の文書。FAQなど。

オープンソースならでは: 読んでいるコードに特徴的な識別子をいくつか選んでメーリングリストなどのアーカイブを検索してみる。作者に直接問い合わせてみる(濫用禁止、対価をコミュニティへ還元せよ、作者はボランティアであることを忘れるな)

8.5 Common Open-Source Documentation Formats

オープンソースで用いられる文書形式の紹介: man (mdoc), Texinfo, DocBook, javadoc, Doxygen。


この記事へのトラックバック
この記事へのコメント
コメントを書く
お名前: [必須入力]

メールアドレス:

ホームページアドレス:

コメント: [必須入力]

認証コード: [必須入力]


※画像の中の文字を半角で入力してください。

広告


この広告は60日以上更新がないブログに表示がされております。

以下のいずれかの方法で非表示にすることが可能です。

・記事の投稿、編集をおこなう
・マイブログの【設定】 > 【広告設定】 より、「60日間更新が無い場合」 の 「広告を表示しない」にチェックを入れて保存する。


×

この広告は1年以上新しい記事の投稿がないブログに表示されております。