Python代码可读性

Question

我之前主要用的是静态类型的编程语言，现在用Python写代码，感觉在可读性上有些困难。比如，我有一个叫做Host的类：

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风格的做法是用例子来说明文档。如果可以的话，说明一个对象需要支持哪些操作才能被接受，而不是具体的类型。

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 2

文档字符串的规范可以在 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
    ...

还有一个提案被拒绝了，内容是关于为属性写文档字符串（而不是构造函数的参数）。

Answer 3

使用动态语言会让你明白一些关于静态语言的事情：你在静态语言中得到的那些帮助，现在在动态语言中你会觉得缺少了，但其实那些帮助并没有那么重要。

拿你的例子来说，在静态语言中，你会知道参数是一个字符串，而在Python中你就不知道了。所以在Python里，你需要写一个文档字符串。在写这个文档字符串的时候，你会发现你想说的比“它是一个字符串”要多得多。你需要说明字符串里包含什么数据，它应该是什么格式，默认值是什么，还有一些关于错误情况的信息。

然后你会意识到，其实你也应该在静态语言中把这些都写下来。没错，Java会强制你知道它是一个字符串，但还有很多其他的细节需要说明，而在任何语言中，你都得手动去做这些工作。