かなり大きな背景を持ついくつかの小さなコードのコメントを書く
そのため、ベジェ曲線をパーツに分割することに関連するコードを記述する必要がありました。私はいくつかのリファレンスを読み、特にこれについて言及しました 詳細なもの 。
ただし、最終的なコード結果は20〜30 LOC程度です。しかし、このような背景がなければ、誰かがコードが何をしているかを理解することは本当に難しいでしょう。
それを詳細に説明するには、関数の説明としてあまりにも多くのコメントを書く必要があります。
このドキュメントへのリンクをコメントに入れることは、あまりいい考えではなかったようです（リンクが将来壊れる可能性があります）。
Q.これをドキュメントとして生成し、プロジェクトドキュメントでローカルに保持し、コメントで参照する必要がありますか？
Q.特定の機能に関連する複雑で大規模な作業領域についてコメントする、他のより一般的な方法。
追伸私は後でこのコードを読んで、それが何であるかを私に呪いたくないので、あなたは見る：p
複雑なアルゴリズムの「なぜ」と「どのように」の詳細を説明する大きなコメントセクションを持つことは良い考えです。そして、開発者がコードについて読むためにコンテキストを切り替える必要がないように、コードに近いほうが良いです（さらに悪いことに-アルゴリズムとドキュメントを交互に切り替える）。
実装の詳細なしでアイデア/概要のみを取得する必要がある人のために、長いコメントの上に一種のTL; DRを含めることを忘れないでください。
追伸私は数か月前にそのようなコメントブロックでプロジェクトを移植していました-それらは非常に役に立ちました。
コードは書かれたよりもはるかに頻繁に読み取られるので、注意深く書かれたコメントは、金で割った価値があります。
コードの記述中に参照した記事の関連する詳細を抽出します。 URLが含まれている場合は、将来壊れる可能性があります。常にインターネットアーカイブがあります。そして何よりも、De Casteljauのアルゴリズムなど、使用した理論上の結果を具体的に参照してください。
読者がコードを理解するための詳細な参照howを見つけることができる限り、ドメイン（この場合はスプラインと数値分析）に精通していない人にとってコードが不透明であっても問題ありません。
コードを理解するのに十分な情報を含むコメントがある場合、私は個人的に気に入っています。それを別の場所に保存すると、誰かがコードを理解しようとするまで、これが失われる可能性が常にあります。それでも、そこにリンクを張ってください（うまくいくかもしれませんが、多分それはウェブアーカイブにあるでしょう）論文があれば、そこにタイトル/著者を置いて見つけられるようにします。
しかし、それでもフィールドを知っている人は、コメントを読んで何が起こっているのかを理解するだけで十分です。
de Casteljauについて聞いたことがないので正確にはわかりませんが、おそらく次のようなものがいいでしょう。
Splitting the curves into parts because [thats more awesome|i like it|faster›...] using de Casteljau's algorithm.
The following differs from the usual de Casteljau's algorithm:
a. all control points are cats
b. we calculate using roman numerals
Maybe a reason why this differs.
A detailed description is at http://pomax.github.io/bezierinfo/#decasteljau
Also the paper "Towards the use of cats as curve points" by "Meow et al." is of great use (link to paper maybe)
If you want, more detailed description
これは、コードを理解するか、（その背後にある理論を知らない場合）説明のソースを見つけるのに十分な情報を提供するはずです。
長いコメントの唯一の欠点は、ファイルサイズと、コメントをスクロールする必要があることです。どちらも実際には問題ではありません（今日のファイルサイズは組み込みシステムなどにのみ重要であり、コメントはバイナリにありません。20行のコメントをスクロールする必要があることについて不平を言う人はIDEを取得する必要があります）
これについて考えてください：誰かがそのコードの一部を数年で変更しなければならない場合、会社が彼を雇うのにもっとコストがかかるでしょう：
- 彼は理解しているコードを編集している間、大きなコメントを無視する必要があります
- 彼はこのコードがどのように機能するかについて情報を検索するか、それを書き直す必要があります。それは、docsフォルダーにあるそれを説明するファイルが失われ、リンクが切れているためです。
注：なぜコードにドキュメンテーションが存在する必要があるかについての議論は、この回答の下部にあるセクションで行われます。
アルゴリズムの詳細をコメントとして含めることをお勧めします。
なぜこのアルゴリズムなのか？
アルゴリズム自体を説明する前に、代替アルゴリズムではなく、このアルゴリズムが選択された理由を最初に説明する必要があります。
説明は「ベジェカーブを使用します。十分に機能するため、他の代替案は検討されていません」のように単純なものにすることができます。ただし、代替案をテストした場合は、それらが拒否された理由を説明してください。
ここでの考え方は、後から来るメンテナが再度調査する必要があるかもしれないということです（たとえば、より良いパフォーマンスや精度を探すために）、すでにアルゴリズムXとYで作業を行っていて、拒否された理由がまだ当てはまる場合、メンテナは、実験を繰り返すのではなく、別のアルゴリズムのチェックを開始することを決定できます。
どのアルゴリズムですか？
なぜこれがばかげているように見えるかもしれませんが、 "Bezier Curves"と言ったように、アルゴリズム/データ構造/ ...（B-Tree、B + -Tree、B * -Treeなど）のわずかなバリエーションがあることを覚えておいてください。したがって、どのアルゴリズムを選択し、どのソースから取得したか（できればオンラインで入手できることが望ましい）をできるだけ正確に指定すると、読者の期待に応えることができます。
また、これが一般的な教科書のバージョンと比較してバリアントである場合、それがそのように明確にラベル付けされていることを確認してください。
このアルゴリズムはどのように機能しますか？
これは、実際に作業するチームによって異なります。 Bezier Curvesがチームのパンとバターである場合、単純なワンライナーで十分かもしれません。ただし、サーフフィギュアのように聞こえる人がコードを読んだり保守したりする可能性がある場合は、アルゴリズムの説明が最適です。
第二に、アルゴリズムをコメントで記述することのもう1つの利点は、記述を分割し、プログラミングスタイルを読みやすくすることです。つまり、最初にセクションのみを識別するアルゴリズムの一般的な概要から始め、次にセクションごとにコメントブロックを、関連するコードのすぐ下に配置します。コードがコメントで十分であることを確認するのが簡単になります。
最後に、アルゴリズムをコメントで記述する最後の利点は、アルゴリズム自体に注釈を付けることができることです。ショートカットを取ることもできます（たとえば、精度のニーズには2回ではなく1回の近似で十分です）、または逆に、特定のステップが必要な理由（およびそれを削除した場合の結果）について説明します。アルゴリズムをfixすることもできます（たとえば、印刷されたバージョンを指定した場合、エラッタがある可能性があります...）。
どこ？
これは実装の詳細なので、呼び出し元の邪魔になってはいけません。実装の詳細はinで文書化し（外部ではなく）、ドキュメントジェネレーターによっては、「純粋な」コメントを使用する必要があります。ドキュメントで。
なぜinin the code？
私は、コードのドキュメンテーションはコードに可能な限り近いところにあるべきだと主張します。理由は簡単です：
- バグ追跡システムが変更される可能性があり、インポートツールが機能していてもIDが変更される可能性があります
- ソース管理システムが変わる可能性があります
- リポジトリは再編成されたり、いくつかに分割されたりすることがあります...
- ...
このようなイベントが発生すると、（新しい）境界を越えたリンクが切断されるリスクがあります。
コードは唯一の定数です！
確かに：
- コードがなければ、ドキュメントは必要ありません
- コードを使用すると、コメントが得られるため、
したがって、コードに含まれている場合は、ドキュメントが利用可能になる可能性が高くなります。
明らかに制限があります。たとえば、テキストファイルには画像を含めることができないため、グラフィックスや図をコメントに含めるのは困難です（ASCIIアートを過小評価しないでください。そうです、私は真面目です）。まだテキストは長い道のりなので、少なくとも適切な説明を適切に提供でき、他の場所でより詳細な説明を提供してリンクすることを妨げるものは何もありません。
他のすべての答えは「コメントに入れて！」
細かい点に逆らって、代わりにコードと一緒に別のドキュメントに保存することをお勧めします。これは、コードが理解するのに複雑な数学を必要とする何かを実行しているように見えるためです。数学は、最良の場合を理解するのに十分難しい場合があります。適切な標準表記法がないと理解するのがさらに難しくなる可能性があり、コードのコメントは空想的な数学表記法を配置するのは簡単ではありません。アスキーアートはこれまでのところあなたを得ることができるだけです。
代わりに、私は簡単に述べるコードコメントのアルゴリズムとドキュメントを参照を使用して、適切なツールで作成し、詳細なファンシー数学を表示できます。このドキュメントがコードと同じリポジトリに配置されていることを確認し、リポジトリから別のリポジトリへの、またはバージョン管理システムから別のバージョンへのコードの今後の移動で省略されそうにない場所に保存します。これらのことが起こります！
私が作業している場所では、プロジェクトに関連付けられているすべての公式ドキュメントには、後でドキュメントを取得するために使用できるパーツ番号が付けられています。このアプリケーションが開発されている同様のプロセスがある場合は、ドキュメントに割り当てられた番号を取得することを検討し、コードコメントでその番号を参照して、失われた場合でも常にそのドキュメントを追跡する方法があるようにします。