Руководство по стилю кода

Это руководство содержит информацию и рекомендации по написанию кода для BeeWare.

Стиль кода

BeeWare следует PEP 8 в нашем коде, за исключением длины строки, увеличенной с 79 до 88 символов. Мы используем Ruff для обеспечения соблюдения конвенций PEP 8, где это возможно. При фиксации кода pre-commit запускает проверки, в том числе Ruff. Где это возможно, он автоматически форматирует ваш код, чтобы обеспечить его соответствие нашим стандартам форматирования и стиля. Вы можете настроить некоторые IDE на автоматический запуск Ruff при сохранении, что может помочь в этом процессе.

Помните, что наиболее важной частью PEP 8 является Раздел 0: Глупая последовательность — это кошмар мелких умов. Существуют ситуации, когда следование PEP 8 не имеет смысла, и важно понимать, что в таких случаях допустимо, а иногда даже предпочтительно, писать код, не соответствующий перечисленным правилам. Знание того, когда можно отступать от этих правил, так же важно, как и соблюдение согласованности в большинстве ситуаций.

Одно из проявлений этого можно увидеть в правилах именования. Библиотекам BeeWare часто приходится взаимодействовать с другими языками. При создании обёртки для других языков желательно (а в некоторых случаях и необходимо) следовать правилам именования целевого языка, а не Python. Например, при вызове или обращении к коду Java функции должны использовать символы mixedCase, как это принято в Java, а не snake_case, как рекомендуется в PEP 8.

Мы следуем американскому правописанию при наименовании API, переменных и т. д.

Кроме того, в PEP 8 есть некоторые дополнения, относящиеся конкретно к BeeWare:

Разделение длинных вызовов функций

Если вызов функции с несколькими аргументами не помещается в одной строке, каждый аргумент следует размещать в отдельной строке, а после последнего аргумента ставить запятую. Ruff допускает (и будет предлагать) формат, при котором несколько аргументов помещаются в одной строке с переносом:

my_function(
    arg1, arg2, arg3
)

Этот стиль использовать не следует. Вместо этого расставьте аргументы по одному в строке, добавив запятую после последнего аргумента:

my_function(
    arg1,
    arg2,
    arg3,
)

Разделение длинных строк

Если строковый аргумент необходимо разбить на несколько строк, чтобы соблюсти ограничения по длине строки, заключите соединенные строковые литералы в скобки, чтобы было ясно, что эта строка представляет собой один аргумент. То есть мы предпочитаем:

my_function(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

перевод:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    second_argument,
)

Что следует избегать

Мы стараемся по возможности избегать модулей utils, понимая, что иногда они неизбежны. Предпочтительной альтернативой является поиск места для данной функции в другом месте исходного кода, вместо использования модуля utils.

Как правило, мы стараемся избегать или откладывать любой дорогостоящий код инициализации, чтобы обеспечить более быстрый запуск приложения. Например, модули в пакете toga-core загружаются «по мере необходимости» — они импортируются только по запросу, а не заранее. Это ускоряет запуск и позволяет тратить время только на то, что действительно использует приложение.