コードコメントに設計の決定を文書化しますか？
ソースコードでコード設計の決定を文書化するにはどうすればよいですか？私が正しいと思う時点で大量のコメントを追加する必要がありますか？
それとも、別のファイルを作成するだけですか？
この問題は私にとって重要です。将来私が取り組んでいるプロジェクトが他の誰かに引き継がれる可能性があるため（または、おそらく何年も離れた後、プロジェクトに戻る可能性があります）、なぜ私がコードを取ったのかを理解する必要があるからです。何らかの方法で設計を決定し、他の方法では決定しません。
理想的には、コードのコメントから（たとえば、reStructuredTextを使用して）コードのドキュメントを生成したいので、自分のオプションが何であるかを知りたいと思っています。
ありがとうございました。
[〜＃〜] edit [〜＃〜]これはトリッキーなユースケースです：何かを生成するメソッドがあるとします。それが生み出すものは、すべて明白なアプローチA、B、またはCによって達成された可能性があります。私がアプローチCを選択したのは、AとBを選択した後、実際には深刻なマイナス面があることが判明したためです（たとえば、サードパーティのライブラリによっては、ライブラリの開発者に連絡した後、十分に維持されていないことが判明しました。 ）、しかしそれらの欠点はすぐには明らかではありません。
コメントの大きなブロックはコードの行を区切るため、そのメソッドの下のコメントでそのすべてを説明すると、コードは読みにくくなります。これを処理するための最良のアプローチは何でしょうか？
コメントを別のファイルに移動すると、そのファイルが読み込まれることはありません。そのファイルへのポインタを作成することも良い考えではありません。プロジェクトのクリーンな構造を壊してしまうからです。すべてがソースコードの数行できちんとコメント化されています。 。
ソースコードでコード設計の決定を文書化するにはどうすればよいですか？
答えは、「最善」と「設計決定」の理解に依存します。
私がコードで文書化する設計上の決定：
すべてのコメントと同様に、コードで何が行われているのかを理解するために必要以上のコメントを付けないようにしています。コードを読むとき、私はコードが何が起こっているのかを明らかにする方法で書かれていることを期待しています。したがって、私は自分のコードを文書化します。
先に作成された例：
def calculate_total_of_articles(articles):
...
return total
このコンテキストでは、このコードが何をするかは明らかです。記事のコレクションの合計を計算します。これ以上のコメントは不要です。
新しいビジネス要件があるとしましょう。そのため、必要と思われるものから逸脱することができます。たとえば、記事abcdがリストにあれば、無料で提供します-この逸脱をコードで文書化します。
def calculate_total_of_articles(articles):
"""calculates the total, but according to business decision
https://ourtrackerwahtever.com/issue1234
one of abcd comes for free
...
"""
私が説明します
- 何が違う
- なぜ違うのか
- その決定の詳細/理由を見つける場所
別の例：たとえば、記事を名前でソートする必要があるとします。そして、あなたはquicksortや他のいくつかのアルゴリズムの代わりにbubblesortを実装することに決めました、私はそれをコードで文書化しません。私は、コードが理由による方法で書かれていることを期待しています。決定について疑問がある場合、または改善の提案がある場合は、元の作者に質問して、改善方法を提案します。次のようなコメントは期待していません
私はバブルソートが醜いことを知っていますが、この場合はそれが最善の解決策です
通常、コンテキストは、なぜそれを行ったのかを明確にする必要があります。
私が正しいと思う時点で大量のコメントを追加する必要がありますか？私にはその利点は見当たらない。
私にとってはsource fileは指示についてですwhatを実行する必要があるか、またはこのコードが実行する必要があることを通知します。 whyの質問は私にとって二次的です。
頭の中の声は私にこのようにコードを書くように言った
上で述べたように、もちろんexceptional期待を文書化する必要があります。理由は他の場所で与えることができます。そして読者が興味を持っているなら、彼は従うかもしれませんが、彼女/彼はreading codeのコンテキストを離れなければなりません。
それとも、別のファイルを作成するだけですか？
私はそれに苦労しています。それはどのファイルですか？ドキュメンテーションセクションでそれを行うことができます。しかし、一方で、私がドキュメントに期待する開発者として、それは、可能な目標を達成する方法、コードの使用方法を教えてくれますが、特定のことをした理由の秘密の日記ではありません。
考えれば考えるほど、結論に近づきます。
いいえ。コードと一緒にある限り、個別のファイルは適切な場所ではありません。
tl; dr
それでは、理由/決定をどこに文書化するのでしょうか？
プロジェクトWiki
プロジェクト（バグ）トラッカー
プロジェクトページ
プロジェクトブログ
これらは、コードを理解するために関係のないことをコードベースに残さず、長い説明を避けるという前提を受け入れる場合に最適です。
それはあなたの説明の範囲に依存すると私は主張します。
設計の決定が非常に細かく、1つのメソッドで完全に実装される場合は、そのメソッドの横にあるコメントが適切です。
設計上の決定が単一のクラスに影響する場合は、それをクラスとともに文書化する必要があります。
デザインがプロジェクト全体に影響を与える場合は、おそらくドキュメントを独自のファイルに配置する必要があります。
要するに、ドキュメントが見つかる可能性が最も高い場所にドキュメントを置くです。
説明を非常に長くする必要がある場合は、コード内にコメントとして簡単な概要を記述し、行外ドキュメントのより詳細な説明へのポインタを含めます。
一般に、コードドキュメント自体をできる限り多くして、コメントを最小限に抑えるようにすることをお勧めします（それより少なくはありません！）。コメント。
もちろん、これが容易ではない、または不可能である場合もあります。そのような場合は、コードを十分に明確にするためにコメントに頼る必要があります。
XMLドキュメントコメントでコードを文書化します。実行時にこれらのソースファイルからドキュメントファイルを自動的に抽出する機能が得られます。
XMLコメントは、メソッド/クラスの機能を説明するために使用できます。
READMEファイルに配置できる高レベルのアーキテクチャの前提条件。
yoが次のリーダーである可能性が最も高い場合でも、次のリーダーのためにソースコードに確実に文書化してください。数年後に少しトリッキーなロジックに遭遇したら、自分に感謝するでしょう。