モジュールの長さ推論とコード行に対するドキュメントストリングの比率に関するメッセージPylintメッセージ

Question

これは意見ベースでは解消されるかもしれないが、グーグルが私が望んでいたリソースを見つけることができないと知っている。 Pythonコミュニティでベストプラクティスを確立し合意しました。

私は今までに発明されたすべての言語で難読化されたコードを書いたかなり恐ろしい歴史を持つ組織の中で、中間のPythonプログラマーです。私は本当に良いプログラミングスタイルと実践の例を挙げたいと思います。そのために、私はPEP 8に従っています。私が書いたすべてのものにpylintを走らせ、単純にそれらを却下するのではなく、それぞれの提案について深く考えています。私はより長い、複雑な方法を短いものに分割しました。 http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

自分の組織の唯一のPythonプログラマーではないが、私はこのようなものを真剣に受け入れる唯一の人だと思う。同僚は、特定のスキーマに従わない命名法を用いて、文書化されていない反復コードを気にしていないようです。だから私は自分のコードを見直したり、それらから学習することは私の最善の選択だとは思わない。

私はちょうど、最初に「モジュールが多すぎます」というメッセージをpylintから得ました。私はモジュールを書いていません - 私は、既存のクラスに少なくとも1つのクラスといくつかのメソッドを追加したいと思います。私は、モジュールが「一つのことをしなければならない」というアイデアは知っていますが、「もの」はまだ完全には実装されていません。

+---------+-------+-----------+-----------+------------+---------+ 
|type  |number |old number |difference |%documented |%badname | 
+=========+=======+===========+===========+============+=========+ 
|module |1  |1   |=   |100.00  |0.00  | 
+---------+-------+-----------+-----------+------------+---------+ 
|class |3  |3   |=   |100.00  |0.00  | 
+---------+-------+-----------+-----------+------------+---------+ 
|method |27  |27   |=   |100.00  |0.00  | 
+---------+-------+-----------+-----------+------------+---------+ 
|function |2  |2   |=   |100.00  |0.00  | 
+---------+-------+-----------+-----------+------------+---------+ 

+----------+-------+------+---------+-----------+ 
|type  |number |%  |previous |difference | 
+==========+=======+======+=========+===========+ 
|code  |266 |24.98 |266  |=   | 
+----------+-------+------+---------+-----------+ 
|docstring |747 |70.14 |747  |=   | 
+----------+-------+------+---------+-----------+ 
|comment |41  |3.85 |41  |=   | 
+----------+-------+------+---------+-----------+ 
|empty  |11  |1.03 |11  |=   | 
+----------+-------+------+---------+-----------+ 

私は本当にコードの266行がモジュールのためにあまりにも多くあるとは思わない：ここでは

はpylintが私を与えることを、いくつかの統計があります。私のドキュメントストリングはモジュールの75％です - この標準ですか？私のメソッドはデータの操作が小さいので、私のドキュメントストリングはかなり繰り返します。各docstringは、例えば、一つの引数がpandasデータフレームであり、その意味を持つデータフレームの必須の列とオプションの列をリストし、それがデータフレームに対して何もしない各メソッドや関数で繰り返されることを述べる傾向があります。

ここで私が作っているような系統的なエラーがありますか？コードを改善するために何を読むべきかについてのガイドラインはありますか？私のドキュメントストリングは長すぎますか？あまりにも長いドキュメントストリングのようなものはありますか？私は単純にpylintモジュールを使いすぎてメッセージを消して、私の人生に乗っていくべきですか？

Answer 1

うわー、素晴らしい質問です。高品質なコードを書くという願望を持つことは、それほど一般的ではありません。あなたの同僚についてのアドバイス。彼らの視点を却下しないでください。彼らはおそらく悪い仕事をするつもりはありませんが、ソフトウェア品質の考え方と価値観の考え方を何らかの形で結びつけなければなりません。あなたが書いたコードについて人々に話す時間を取っても、あなたがその経験から得たものすべてではありません。あなたの会社の業績に永続的な影響を与えるためには、組織にソフトウェア品質を尊重し、追求することが必要です。そうでなければ、あなたが書いたコードがどれほど良いかどうかは関係ありません。残念ながら残念です。私はこれが本当にあなたの質問ではないことを知っています。

一部の言語では、Javaのようにファイル内に正確に1つのクラスがあり、そのファイルに含まれるクラスと同じ名前を付けるのが普通です。これはPythonでは普通ではありませんが、私はそれが良い指針を与えると思います。コードをナビゲートしやすくするためには、可能な限り物事をまとめることと、それらを整理することとのバランスを取る必要があります。これが物を分ける主な理由です。だから、あなたの問題空間についてのこの2つの懸念と、あなたのコード内のアイデアがあなたの問題空間におけるアイデアとどれくらいうまく一致しているかを見直すことから始めてみることができます。

私はdoc文字列を使用しますが、私はそれらをスフィンクスまたは再構成またはラテックスで作成しようとしていません。私はDoxygenを使用する大規模なコードベースで作業していますが、筆者のコメントにはこのツールの機能を使用するために多大な努力を払っていませんが、Doxygenのドキュメントでは、以前はフォームのようなコーディングスタイルで作業しましたが、実際には書類作成が価値をもたらしたわけではありません。あなたのコメントの中で重要なのは、あなたがデザインや実装で行っていることと同じです。それは理解です。各コメントの各単語が理解に追加するものは何か。私はName、Parameter、Returnのような無価値のフィラーの言葉を望んでいません...私は、私は人々が自分のインタフェースが何であるかを私に教えてもらいたいので、慎重にしか意味しません。私はすべてのそれらの言葉が私が容認したいと思う書類として見る。私はそれが良いコードを作る素晴らしいコメントのように感じる人々のための罠だと思う。彼らは助けますが、私がコメントしなければならないと感じる場合、2つの事のうちの1つが起こっています：それはインターフェースであるか、それは設計上の欠陥です。私はインターフェイスではないことをコメントしなければならない場合は、おそらく私のデザインがあまり明確でないか、実装が煩雑になっていることを意味します。私がここに再びいるなら、私はおそらくきれいに来るでしょう。

あなたのコードを見ることなく、私はそれを高品質にする方法について多くの助言を与えることはできませんが、 "ソフトウェア品質"の定義方法について考えるのに役立ちます。私はそれを「どのようにコードを変更するのが簡単か」と定義します。これはコードが必要とする可能性のある変更の種類に依存します。つまり、コードの品質を評価するには、必要と思われるものに対する期待が必要です。逆に直感的に言えば、実際にコードを変更しやすくすることは、今必要でないものを実装しようとしないことです。それでも、私はしばしば、特にPythonの中で、少しでも挑発していくつかのことを実装します。 exampleについては、strメソッドを実装することは有効です。 eq、neおよびハッシュを実装することでオブジェクトをハッシュ可能にすることで、オブジェクトを辞書またはセットのメンバーのキーとして使用することができます。

アドバイスの1つの（多少ランダムな）項目は、オブジェクト指向の考え方に注意することです。そんなに良いことがありますが、いくつかの落とし穴があります。たとえば、get_thing（self）のような関数を作成しないでください。属性を持つ方が良い方法です。余分な作業が必要な場合は、@ property getter setterを作成することができます。これにより、呼び出し元には単純な属性アクセスが残っています。私は、オブジェクト指向のアイデアを学んだばかりの人々は、良い方法としてメソッドをたくさん作り、設定するのを見ている傾向があることを知っていますが、私は可能な限り完全にデザインから状態を駆り立てて、メソッドはオブジェクトに状態を意味します。