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

Это руководство содержит информацию и рекомендации по написанию кода для 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:

Хотя аннотация типов в соответствии с PEP 484 не является обязательной, её использование по-прежнему настоятельно рекомендуется, особенно в публичных интерфейсах API.

Ниже приведен пример стандартного определения функции с правильными указаниями на типы и строкой документации Sphinx:

def function_name(param1: int, param2: str) -> bool:
"""Пример функции с указанием типов и описанием.

:param param1: Первый параметр.
:param param2: Второй параметр.

:returns: Возвращаемое значение. True в случае успеха, False в противном случае.
"""

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

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

my_function(
    arg1, arg2, arg3
)

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

my_function(
    arg1,
    arg2,
    arg3,
)

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

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

my_function(
    (
 "это очень длинная строка"
 "которая разбита на две строки"
    ),
    second_argument,
)

перевод:

my_function(
    "это очень длинная строка",
    "которая разбита на две строки",
    second_argument,
)

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

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

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

При написании комментариев избегайте использования местоимений первого лица множественного числа, таких как «мы» (например, пишите «Loop over» вместо «We loop over»).

В описаниях тестов укажите ожидаемое поведение, которое демонстрирует каждый тест. Не включайте вступительные фразы типа «Проверяет, что» или «Убеждается, что».

Сохраняйте ссылки на тикеты для нестандартных случаев, когда в тикете содержатся дополнительные сведения, которые сложно описать в документации или комментариях. Указывайте номер тикета в конце предложения следующим образом:

def test_foo():
 """Тестовая строка документации выглядит так (#123456)."""