擅长:python、mysql、java
<p>文档字符串约定在<a href="http://www.python.org/dev/peps/pep-0257/" rel="noreferrer">PEP-257</a>中比PEP-8详细得多。</p>
<p>然而,docstring似乎比其他代码领域更加个人化。不同的项目会有自己的标准。</p>
<p>我总是倾向于包含docstring,因为它们倾向于演示如何使用函数以及函数的运行速度。</p>
<p>我更喜欢保持事物的一致性,不管字符串的长度如何。我喜欢缩进和间距一致时的代码外观。也就是说,我用:</p>
<pre><code>def sq(n):
"""
Return the square of n.
"""
return n * n
</code></pre>
<p>结束:</p>
<pre><code>def sq(n):
"""Returns the square of n."""
return n * n
</code></pre>
<p>并倾向于在较长的文档字符串中不评论第一行:</p>
<pre><code>def sq(n):
"""
Return the square of n, accepting all numeric types:
>>> sq(10)
100
>>> sq(10.434)
108.86835599999999
Raises a TypeError when input is invalid:
>>> sq(4*'435')
Traceback (most recent call last):
...
TypeError: can't multiply sequence by non-int of type 'str'
"""
return n*n
</code></pre>
<p>意思是我发现这样开始的docstring很混乱。</p>
<pre><code>def sq(n):
"""Return the squared result.
...
</code></pre>