技術文書（コード文書）
出典: フリー百科事典『ウィキペディア（Wikipedia）』 (2021/09/20 16:08 UTC 版)
「ソフトウェアドキュメンテーション」の記事における「技術文書（コード文書）」の解説
これは、多くのプログラマが「ソフトウェアドキュメンテーション」という用語で想定している文書である。ソフトウェア開発では、コードだけでは不十分である。コードと共にそれをどう使うかといった様々な事柄を記述した文書が必要である。このような文書はソースコードに埋め込まれていることが多く、ソースコードを入手すれば同時に参照可能となることが多い。 この文書は非常に技術的で、主にAPI、データ構造、アルゴリズムなどを定義し解説する。例えば、m_name という変数が人間の名前を参照するものである、というような説明が書かれる。コード文書は完全であることが重要だが、同時に保守性を考慮して冗長性をなるべく排除しなければならない。 Doxygen、Javadoc、ROBODoc、POD、TwinText といったツールでコード文書を自動生成できる。これらツールはソースコードからコメントを抜き出して、テキストまたはHTMLの形式でリファレンスマニュアルを作成するものである。コード文書は「リファレンスガイド」のスタイルで構成されることが多く、プログラマが素早く任意の関数やクラスを検索できるようになっている。 多くのプログラマがいくつかの理由から文書の自動生成を活用している。例えば、ソースコードにコメントの形で文書が埋め込んであると、プログラマはコードを書くのに使っているツールで文書も同時に書くことができ、コードを見ながら文書を書くのに便利である。これにより、コードと文書を常に同時更新するのが簡単になる。 もちろん欠点もあり、プログラマ以外がこの形式の文書を編集できないという一面もあり、プログラマ以外はツールによって更新されるまで最新の文書を参照できない（例えば、ソースからの文書生成は毎晩まとめて行われたりする）。もっとも、このような特徴を利点と見る考え方もある。 ドナルド・クヌースは、ソフトウェアドキュメンテーションをコードを書いた後で行うのが非常に難しいと考え、文芸的プログラミングという手法で文書をソースコードと同時に書くようにして、自動的手段で文書をソースコードから抜き出すようにした。
※この「技術文書（コード文書）」の解説は、「ソフトウェアドキュメンテーション」の解説の一部です。
「技術文書（コード文書）」を含む「ソフトウェアドキュメンテーション」の記事については、「ソフトウェアドキュメンテーション」の概要を参照ください。
- 技術文書のページへのリンク
