Python中的单独部分

Question

我想知道是否有一种在Python中分离代码块的最佳实践。例如，在MATLAB中，两个注释符号（%%）创建一个代码段。目前，我正在做：

####
## Import libraries
####

import _mssql #Binary here: http://www.lfd.uci.edu/~gohlke/pythonlibs/#pymssql

####
## Connect to db + Query the data
####

q_file = open ("query.txt", "r")
query = q_file.read().replace('\n', '')

##Connect to the database
conn = _mssql.connect(server='', user='',
                      password='', database='')

##Query the database
conn.execute_query(query)
for row in conn:
    print(row)

####
## Data filtering
####

[...]

Answer 1

顶层使用模块，在各自的模块中实现单独的部分，然后参考主模块中的部分：

import random
import time

if time.time() > random.random():
    pass

下一级（可选，谨慎使用）使用类

class Foo:
    def function1():
        pass

class Bar:
    def function2():
        pass

下一级，您需要什么，使用函数

def connect(...):
    filename = ...
    params = ...(filename)
    return mysql.connect(*params)

def mainloop(...):
    for xx in connect():
        pass

子级使用块

def foo(path=None, port=None):
    if not path:
        filename = ...
        path = ...(filename)

    if not port:
        foobar = ...
        port = ...(foobar)

    xxx.connect(path, port)

子级使用空行和注释

def foo(...):
    bar.bar()

    assert path  # <-- this is essentially a comment
    smth_with(path)
    some_other()
    data = xxx.yyy()

    assert data
    foo = blahblah
    bar = lambda: blahblah
    filtered = filter(yada, data)

    # data is clean at this point  # <-- an actual comment
    for x, y in data:
        foo.bar.baz()

最后的想法像在OQ中这样的大型注释块显示“代码气味”。您现在开始想知道如何组织您的代码是正确的：）

Answer 2

Python很自然地提供了一个模块化的结构，并为每一层结构提供了文档字符串。

您的注释通常属于函数名或方法描述。然后代码自然读取。（有些评论太明显了，以至于毫无用处，比如“导入库”。）

"""
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"))

请参阅进一步的PEP 257以指导您的文档工作。