既存のコードベースを文書化する方法

私は、インラインドキュメントも技術ドキュメントも持たない既存のアプリケーションのチームの一員として働いています。アプリケーションのさまざまなバグレポートに取り組んでいるので、さまざまな場所にあるバグ番号-バグ番号を書いて、次の開発者がそのバグ番号を参照して何が起こっているのかを確認できるようにしました。

したがって、私の質問は次のとおりです。

このコードを文書化する最も効率的な方法は何ですか？領域に触れたときに文書化する必要がありますか（ウイルスの場合はウイルス手法）、またはアプリケーションの他の領域に分岐するパスをたどらないで、各セクションから単独で文書化する必要がありますか？以前に存在しなかった場所にインラインコメントを挿入する必要があります（コードが何をするかを誤って特定する恐れがあるため）。

既存のインラインドキュメントも、外部ドキュメントへのインライン参照もない、かなり大きなアプリケーションを正確かつ迅速にドキュメント化するには、どの方法を使用しますか？

レガシーコードベースの文書化

レガシーコードベースでスカウトルールに従うことを強くお勧めします。レガシープロジェクトを個別にドキュメント化しようとすることは、決して起こりません。

コード内ドキュメント

最も重要なことは、選択した開発環境でドキュメント機能を使用することです。つまり、Pythonのpydoc、javaのjavadocまたはC＃のxmlコメントを意味します。これらにより、コードの記述と同時にドキュメントの記述が簡単になります。

戻ってきて後で物事を文書化することに依存している場合、それを回避することはできませんが、コードを書いているときにそれを行うと、文書化する必要があるものが頭に浮かぶでしょう。C＃には、XMLドキュメントが不完全または実際のコードと一致しない場合にコンパイル警告を発行するオプションもあります。

ドキュメントとしてのテスト

別の重要な側面は、適切な統合と単体テストを行うことです。

多くの場合、ドキュメントはクラスとメソッドが単独で行うことに集中し、それらを一緒に使用して問題を解決する方法をスキップします。テストでは、これらが互いにどのように相互作用するかを示すことにより、これらをコンテキストに入れることがよくあります。

同様に、単体テストでは、モックアウトが必要な外部依存関係を明示的に指摘することがよくあります。

また、テスト駆動開発を使用すると、使いやすいソフトウェアを作成することがわかります。優れたテストフレームワークでは、コードをテストしやすくすることと使いやすくすることは、多くの場合同じことです。

高レベルのドキュメント

最後に、システムレベルとアーキテクチャのドキュメントについて何をすべきかがあります。多くの人は、このようなドキュメントをwikiで書くか、Wordや他のワードプロセッサを使用することを推奨しますが、私にとっては、このようなドキュメントの最適な場所は、コードと共に、バージョン管理システムに優しいプレーンテキスト形式でもあります。

コード内のドキュメントと同様に、コードリポジトリに高レベルのドキュメントを保存すると、常に最新の状態に保つことができます。また、コードのバージョンXYを取り出すと、ドキュメントのバージョンXYも取得できるという利点があります。さらに、VCSフレンドリ形式を使用する場合、コードと同様に、ブランチ、差分、マージが簡単になります。

htmlページとpdfドキュメントの両方を簡単に作成でき、LaTeXよりもはるかに使いやすく、必要なときにLaTeXの数式を含めることができるので、私はrstがとても好きです。

ひっかけ問題。基本的には、「リファクタリング」メソッドを使用します。これは、「コードに触れた場合、ドキュメント化する」と言い直します。

しかし、正確には; 問題が発生し、発生するバグを修正するためにコードに精通する必要がある場合、特にそのコードにコメントを書くためにその精通度を使用する必要があると思います。本質的に、バグを修正する動機は、その時点で、コードを文書化できるように十分にコードに精通することを余儀なくされました。そのため、無関係なブランチをフォローしたり、無関係な関数をドキュメント化したりするのが嫌です。なぜなら、その時点で（バグ修正を検証するために）コードのアクティブなテストを行っていない場合、コードの機能とその理由を正確に理解していることを確認してください。（バグ修正をテストする場合でも、コードが何を、なぜそれを行うのかを正確に把握するのが難しいという問題に取り組んでいません;あなたは

このアプローチは、全体の速度を犠牲にして精度を最大化する傾向がありますが、同時にコードを厳しく維持する必要性に影響を与えません。もちろん、バグ修正の仕事が少ない場合は、「未知の領域」に飛び込んでそこで文書化を開始できますが、（ほとんどの人と同様に）コードを修正して文書化するのに十分な時間が見つからない場合は、良い妥協です。

ひとつ注意すべき点もあります。優れた外部ドキュメントが必要です。あなたのコードには外部ドキュメントへの参照がないと言います。ただし、このような外部ドキュメントが存在することを願っています。そうでない場合は、実際に外部ドキュメントを書くことを最優先事項にします。機能仕様レベルの何かは、すべての大きなソフトウェアプロジェクトにとって絶対に重要だと思います。その理由は、機能仕様、またはそのフォームの高レベルのドキュメントが、ソフトウェアの「機能クリープ」または「機能ドリフト」の防止に役立つためです。また、機能のドリフト（特に）は、ドキュメントが古くなる可能性があるため、ドキュメントを破壊する可能性があります。（私は、ソフトウェアへの機能のプログレッシブ（および迷惑な）追加として機能クリープを定義します;機能ドリフト一方、ソフトウェアが実行する一連のアクションは、時間の経過とともにゆっくりと変化します。機能クリープは付加的です。つまり、通常、ソフトウェアの機能セットを増やすことを伴います。一方、機能のドリフトはゼロサムです。ソフトウェアが最初に意図したものとは完全に異なることを行うまで、エッジ機能の1つが1つずつ、異なることを行うように定義されます。機能のドリフトはまれですが、ドキュメントには致命的です。）

2年間にわたって共同開発したアプリケーションの1つに、ドキュメントが大幅に欠けていました。ある時点で、その時点からアプリケーションを維持する別の開発者にアプリケーションを渡すことが明らかになったため、コードを文書化する必要がありました。

ドキュメンテーションプロセスの巨大な範囲に対処するために、特定の機能またはアプリの一部のすべてのコードを特定の日にドキュメント化してみます。特定のパターンはありませんでしたが、毎日いくつかのことを行い、毎日ファイル全体またはアプリのセクションを文書化することで完了の感覚を得ることに固執しました。

アプリケーション全体を文書化するには数か月かかりましたが、1日30分（最大）でプロジェクトスケジュールに実際に食い込むことはなく、文書化に伴う多くの退屈な作業を回避しました。

C＃でXMLドキュメントを使用し、ドキュメント作成を容易にするのに十分な機能と構造を提供しました。C＃アプリのドキュメントを作成していなくても、最初に短い要約を書いてから発言するというパターンは非常に危険です。

コードを追加/変更したときに文書化します。それ以外は、公開APIまたはモジュール間のインターフェイスも文書化します。すべてのコードを文書化する場合、費やした時間のROIが表示されない場合があります。Wikiのようなものを使用して、開発中に外部ドキュメントを整理すると便利な場合があります。最後のプロジェクトを開始したときに参照した最も有用なドキュメントは、アーキテクチャドキュメントです。使用されているテクノロジに関する情報が含まれており、アプリケーションがどのように階層化されているかについての高レベルのビューを提供しました。

Doxygenコメントを使用します。Doxygenには、他のほとんどの無料形式よりも多くの出力形式があり、簡単に習得できます。

私たちの何人かは生計のためにそれをするので、あなたはこれをするために請負業者を雇うことを考えるかもしれません。ただし、この選択では、ドキュメントのレビューにコミットする必要があります。

別の一般的な手法は、コードの文書化に新しいdevを割り当てることです。次に、新しい人がそれぞれ速度を上げて通過するようにします。一部の開発者は、これを根管の確保と見なしていることに注意してください。これは、直接的なケースLOLでのみ必要です。

何かを文書化する前に、標準を作成します。これは、関数またはクラスヘッダーの上に、より公式で冗長なもの（javadocなど）の上に数行書くことを確認するのと同じくらい簡単です。誰もがコードをチェックインする前に、ドキュメントはその標準を満たしている必要があります。

私がうまくいったのは、以前に文書化されていなかった作成した関数の関数ヘッダーの前によく書かれたコメントを追加し、追加したものにインラインコメントを追加することです。あなたが触れていないコードを文書化することを避けたい。コメントがないよりも悪いコメントがある方が悪いです。これを「すばやく」文書化する場合、おそらく悪いコメントを書くでしょう。