<p>Python很自然地提供了一个模块化的结构,并为每一层结构提供了文档字符串。</p>
<p>您的注释通常属于函数名或方法描述。然后代码自然读取。(有些评论太明显了,以至于毫无用处,比如“导入库”。)</p>
<pre><code>"""
Perform stuff. Obviously this documentation should be more specific in reality.
"""
import _mssql # Binary here: http://www.lfd.uci.edu/~gohlke/pythonlibs/#pymssql
def run_query(filename):
"""
Open connection to database, run the query in the file, and
return rows as a list.
"""
rows = []
# Minor tweak: "with" takes care of closing the file when you're done
with open (filename, "r") as q_file:
query = q_file.read().replace('\n', '')
conn = _mssql.connect(server='', user='',
password='', database='')
conn.execute_query(query)
for row in conn:
# Maybe use yield here instead of reading all the results into memory
rows.append(row)
return rows
def filter(rows):
"""
Filter a list of rows: Remove any rows containing 'Albuquerque'.
"""
# ....
results = filter(run_query("query.txt"))
</code></pre>
<p>请参阅进一步的<a href="https://www.python.org/dev/peps/pep-0257/" rel="nofollow noreferrer">PEP 257</a>以指导您的文档工作。</p>