docstringに含める情報の量
平均的な複雑さのいくつかのクラスを引数として取る関数があります。
その関数のdocstringを書くとき、私は一連の質問に遭遇しています：（関数が何をしているかに加えて）それらのクラスも記述すべきでしょうか、それとも読者がクラス定義を掘り下げると仮定できますか？または、クラスが定義されている場所を指す必要がありますか？ベストプラクティスは何ですか？
現代のIDEは、読者が1回のマウスクリックで参照されたクラスの定義にジャンプできるようにする必要があります。この情報を繰り返す意味はありません（データの非正規化は時々良いアイデアですが、ソフトウェアのドキュメントで）。
したがって、StringDistanceメソッドがStringsを引数として取る場合は、文字列が何であるかを記述しないでください。 LoanRiskCalculatorがLoansを使用する場合、Loansも記述しないでください。その情報は、Loanクラス内に配置するのが適切です。
Edgeのケースは、引数クラスが、このメソッドまたはこのクラスで使用するために多かれ少なかれ有用な専用ヘルパークラスonlyである場合です。次に、それらを提供するアルゴリズムと一緒に説明することをお勧めします。関連する他のメソッドと通信するためにStringDistancesを使用するReverseTrieLookupTableメソッドは、特定のヘルパーのドキュメントを独自のdocstringに、または少なくともクラスdocstringにプルします。
使用している特定の用語docstringは、Pythonを使用していることを示します。 （またはコブラですが、後者ははるかに可能性が低いです。）
Pythonでは、関連するのはprotocolとnotパラメータのクラスであることに注意してください。 （これはダックタイピング、または実際にはOOと呼ばれます。）したがって、クラスをドキュメント化しないでくださいまったく参照でもコピーでもありません。これらのクラスの定義は完全に無関係です。
isに関連するもの、つまりprotocolは関数がパラメータから期待するものです。あなたはそれを文書化する必要があります。また、関数がその戻り値に対してどのプロトコルを保証するかを文書化する必要があります。