どうすれば複雑なコード構造を文書化できますか？

数学的にも構造的にも非常に複雑で還元不可能なほどのコードがある場合、このコードをドキュメント化するにはどうすればよいですか？特に、私が行う数学または建築のスキルを持っていない可能性のある人がドキュメントからそれを理解できるようにするにはどうすればよいですか？数学もすべて記録する必要がありますか？チュートリアルにリンクしますか？複雑な構造の場合、いくつかの視覚的補助リンクはありますか？

これは、コードと数学がどれほど複雑かによって異なります。コード自体は、常に、できるだけ自己文書化する必要があります。変数に正しく名前を付け、（メガ関数ではなく）論理的で簡潔なメソッドを実装し、必要に応じて（つまり、コードが実際に何を行っているか明らかでない場合）インラインドキュメントを追加します。

非自明なアルゴリズムを使用している場合は、ソースへの参照へのリンクを追加します。これは、開発者があなたが何をしているのかを見つけるための非常に迅速な方法を提供するため、合理的な方法です。すでに述べたように、これは、明白ではないが複雑なアルゴリズムである場合に役立ちます。これは、（a）意味のあることをしていること、（b）誰かがそれが機能していることを証明したことを証明するはずです。

良い例は、あいまいなテキストマッチングに関して行ったいくつかの作業です。私はアルゴリズムについてかなりの研究を行い、「スミス-ウォーターマンアルゴリズム」として知られているものを実装しました（これは実際にはDNA配列に使用されますが、一般的に「マッチング」に適用されます）。したがって、単純にアルゴリズムを実装する代わりに、オンラインで参照を見つけ、1つまたは2つのリンクを含めました。上記のように、これは（a）私のアルゴリズムが公開されたアルゴリズムと一致していること、および（b）アルゴリズムがレビューされて機能していることが示されていることを示しています。

ただし、これは必ずしもコードがどのように機能するか、およびさまざまなクラスが何をすることになっているのかを説明するものではありません。いくつかの「実際の」ドキュメント（システムの開発者ガイド）を書くときは、自分が行ったことを説明し、将来のサポートに十分な情報を提供する必要があります。私の意見では、このドキュメントは技術にとらわれない人でも読めるはずです。「黙示的」である必要はありませんが、専門用語を除外し、想定される知識に依存しないようにする必要があります。

ソースを囲むコメントはあなたが最初にすべきことです。これにより、コードによるドキュメントへの直接リンクが確実に存在します。ドキュメンテーションが非常に複雑な場合は、コメントの要約のみを投稿し、アーキテクチャ/複雑なアルゴリズムのより完全な説明を含む外部ドキュメントへのリンクを検討してください。ただし、複雑すぎない場合は、すべてのドキュメントを1か所に含めることを検討してください。これにより、コード/ドキュメントが同期し、一緒に読み込まれる可能性が最大になります。

チーム/会社が必要とする範囲でコードを文書化します。ジュニアの場合 devはコードを保守するために必要となるため、いくつかの計算について詳細に説明する必要がある場合があります。これは管理上の決定であり、彼らはあなたに必要な時間を与えなければなりません。

あまり開発者がいないことを説明するほど多くのコードを文書化する必要はないと思います。それが問題になる場合は、文書化する時間を与える必要があります。

あなたはそれらのためにウェブ検索をする必要はありません。