Pythonコードの可読性

Question

私は静的型付けされた言語のプログラミング経験があります。今ではPythonでコードを書いていますが、読みやすさに問題があります。

class Host(object): 
    def __init__(self, name, network_interface): 
    self.name = name 
    self.network_interface = network_interface 

私はこの定義から理解していない、どうあるべきか「NETWORK_INTERFACE」：私はクラスホストを考えてみましょう。 「eth0」のような文字列ですか、それともクラスのインスタンスですか？NetworkInterface？私がこれを解決するために考えている唯一の方法は、 "docstring"というコードを文書化することです。このようなもの：

class Host(object): 
    ''' Attributes: 
     @name: a string 
     @network_interface: an instance of class NetworkInterface''' 

そういうものの名前の表記法はありますか？

Answer 1

動的言語を使用すると、静的言語に関することを教えてくれるはずです。静的言語から得たすべての助けは、動的言語では間違っていました。

例を静的言語で使用するには、パラメータが文字列であり、Pythonではそうでないことがわかります。ですから、Pythonではドキュメントストリングを書いています。そして、あなたがそれを書いている間、あなたはそれが「文字列です」よりも、それについてもっと言いたいことを理解しています。あなたは文字列中のどのデータがどの形式であるべきか、デフォルトは何か、エラー条件については何かを述べる必要があります。

そして、静的な言語のためにすべてを書き留めておかなければならないことが分かります。確かに、Javaはそれが文字列であることをあなたに知らせるでしょうが、これらの詳細はすべて指定する必要があります。そして、あなたは手動でその言語で作業する必要があります。

Answer 2

docstringの規約はPEP 257です。

そこの例では、彼らが問題ならば、あなたはタイプを追加することができ、引数を指定するための以下のフォーマットに準拠します。

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    Keyword arguments: 
    real -- the real part (default 0.0) 
    imag -- the imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

属性（というよりも、コンストラクタの引数）のためのドキュメンテーション文字列のために拒否されたPEPもありました。

Answer 3

ほとんどのpythonic解決策は例で文書化することです。可能であれば、特定のタイプではなく、オブジェクトが受け入れ可能であるためにサポートする必要のある操作を記述します。

class Host(object): 
    def __init__(self, name, network_interface) 
    """Initialise host with given name and network_interface. 

    network_interface -- must support the same operations as NetworkInterface 

    >>> network_interface = NetworkInterface() 
    >>> host = Host("my_host", network_interface) 

    """ 
    ... 

は、この時点で、あなたのドキュメントの例は、将来的に作業を続けることを確認するまで doctestにソースをフック。

Answer 4

個人的に私のコードを検証するのにpylintを使用すると非常に便利です。

パイライントの提案にほぼ従うと、コードはより読みやすくなります。 あなたはパイソンのライティングスキルを向上させ、命名規則を尊重します。独自の命名規則などを定義することもできます。特にPythonの初心者にとっては非常に便利です。

お勧めします。

Answer 5

Pythonは、CやJavaと明示的に型指定されているわけではありませんが、まだタイプされておらず、一緒にうまく遊ばないタイプのものを実行している場合は例外をスローします。

あなたのコードが正しく使用され、正しく管理されているかどうか心配している場合は、ドキュメントストリング、コメント、またはより明示的な変数名を使用して、そのタイプを示す必要があります。

使用可能な結果が得られる限り、どの型にも渡すことができるコードを含めてください。

Answer 6

静的タイピングのメリットの1つは、タイプがドキュメントの一種であることです。 Pythonでプログラミングする場合は、より柔軟かつ柔軟に文書化できます。もちろん、あなたの例では、network_interfaceがNetworkInterfaceを実装すべきだと言いたいのですが、多くの場合、型はコンテキスト、変数名、または慣例から明らかです。一般的なことは、パラメータの意味を記述し、その型を暗黙的に与えることです。例えば

：

def Bar(foo, count): 
    """Bar the foo the given number of times.""" 
    ... 

これは、簡潔かつ正確に機能を説明しています。どのようなfooとbar平均が文脈から明らかであり、その数は（正の）整数であることは暗黙的です。ご例えば

、私はちょうど文書の文字列にタイプを言及したい：

"""Create a named host on the given NetworkInterface.""" 

これは、短く読みやすくなり、タイプのリストより多くの情報が含まれています。