web-dev-qa-db-ja.com

実装コードを正式に文書化することは悪い習慣と考えられますか?

PEP-8 は、コードのどの部分にドキュメントが必要かを明確に示しています。

すべてのパブリックモジュール、関数、クラス、およびメソッドのドキュメント文字列を記述します。非パブリックメソッドの場合、ドキュメント文字列は必要ありませんが、メソッドの機能を説明するコメントが必要です。このコメントは、def行の後に表示されます。

(強調鉱山)

上記の抜粋では、非パブリック(a.k.a実装)クラス/関数/モジュールにドキュメント文字列を提供する必要がないと述べていますが、そうすることで、将来のコードのメンテナンスが容易になります。

しかし、私が見るほとんどのpythonコードベースは、PEP-8が上で言っていることを(多かれ少なかれ)順守しているようです;実装クラス/関数/モジュールのdocstringsを省略しています。他のpython開発者がそれをしていないのなら、それはおそらく理由があるのだろうと思われます。

Docstringを実装コードに与え続けるのは悪い習慣でしょうか、それとも単に好みの問題なのでしょうか?

6
Christian Dean

実装コードのドキュメント文字列を書くことは必ずしも悪い習慣ではありません。
1つの注意点は、doc文字列が公式ドキュメントに含まれる場合、他の人が自由に変更できる内部の詳細に依存し始める可能性があることです。それが本当に気になる場合は、ドキュメント文字列ではなく通常のコメントでドキュメントを書くこともできます。

優れたドキュメンテーションを書くことは難しく、ほとんどのプログラマー(私も含む)にとって、コードを書くよりも楽しくありません。次に、コードの可読性に少し自信をつければ、「今書いたばかりのこの内部関数は非常に明確で、追加のドキュメントがなくてもコードはそのまま使用できます」と言うのは本当に簡単になります。そのステートメントの実際の証拠は通常、メンテナンスを行う必要があり、コードが予想よりも自己文書化されていないことが判明した数か月後になります。
ほとんどの場合、そのトラップを回避できれば非常に良いです。

  1. パブリックメソッドは、非パブリックメソッドよりも広い範囲で、より幅広い範囲の人々によって使用されます。

  2. 非公開メソッドは、(アプリケーションが十分に成熟している場合)公開メソッドよりも頻繁に変更されます。

コメントに関しては、私の最初の主張はパブリックメソッドを文書化することははるかに重要ですを意味します。これらは、しばしば必ずしもコードのすべての内部を探索するのに時間(または関心)を持っている必要はないの人がアクセスするメソッドです:彼らはメソッドを使用する必要があるだけで、それを使用する方法を知っています。逆に、非公開メソッドに興味を持つのは、クラスに精通している人です。そうでない場合は、クラスを変更しているため、クラスに精通する必要があります(そうしないと、そもそも非公開メソッドにアクセスする場合)、または関係するメソッド自体にアクセスする場合。

2番目のアサーションは、特にパブリックメソッドと非パブリックメソッドの比率を考慮する場合、非パブリックメソッドのドキュメントを最新の状態に保つことはコストがかかるであることを意味します。 メソッドの変更頻度が高すぎるの場合、何ヶ月または何年も同じままであるパブリックインターフェイスのドキュメントと比較して、ドキュメントを読む人が少ないことを意味します。

結論として、小さいスコープの非パブリックメソッドは、通常、パブリックインターフェイスほど多くのドキュメントを必要とせず、はるかに揮発性があります。言い換えると、非公開の方法を文書化することによって(将来の開発者の時間の観点から)節約される費用は公的な方法より少なくなり、より多くのお金が常に文書を更新するために浪費されます。

これはPEP-8ガイドラインを説明しています。明らかに、非公開メソッドを文書化することが絶対的に重要であるいくつかの例や、公開メソッドが説明不要でコメントを必要としない例も想像できます。それらは、そのPEP-8ガイドラインに従うべきではない場合です。

7

実装コードを文書化することは悪い習慣であるだけでなく、コードベースが大きい場合にも推奨され、必要です。ただし、必要なドキュメントには別のスタイルがあり、パブリックコードのドキュメントとは別の目的を果たします。

公開コードは、ユーザーが何をすべきかがわかるように文書化する必要があります。各ドキュメントは、ユーザーが関数を使用する前に1時間ドキュメントを読む必要がないように、可能な限り説明が必要です。これは、より冗長になる可能性がある場合でも、明確、完全、理解しやすいものでなければなりません。

一方、内部ドキュメントは、コードベースの保守に関心がある人が読むことを目的としています。したがって、プロジェクトに精通していると想定できるため、より簡潔にする必要があります。

個人的には、docstringは実装コードとしては冗長すぎると思います。私は自己文書化コード(つまり、表現力豊かな名前、変数)を目指しており、必要に応じてコメントを追加しています。

もちろん、プライベートコードのdocstring自体には害はありませんが、それらは長く、付加価値のない単純なコメントよりもはるかに多くのメンテナンスが必要であることを覚えておいてください。

4
Paul92

あなたが引用した非常にいくつかの段落では、コメントを使用して非公開のモジュール、関数、クラス、メソッドを文書化する必要があると説明しています。 Docstringはコードのユーザー向けのドキュメントであり、コメントはコードの管理者向けのドキュメントです。

2