Отдельные разделы в Python

Ответ 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)

Subsublevel использует пустые строки и комментарии

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, показывают "запах кода". Вы правы, чтобы начать задаваться вопросом, как организовать ваш код на этом этапе :)

Ответ 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 для руководства вашей документацией.