Керівництво зі стилю написання коду¶

Цей посібник містить інформацію та рекомендації щодо написання коду для BeeWare.

Стиль кодування¶

У нашій кодовій базі BeeWare дотримується PEP 8, за винятком того, що довжина рядка збільшена з 79 до 88 символів. Ми використовуємо Ruff для забезпечення дотримання конвенцій PEP 8, де це можливо. Під час фіксації коду пре-комміт виконає перевірки, зокрема за допомогою Ruff. Там, де це можливо, це автоматично відформатує ваш код, щоб забезпечити його відповідність нашим стандартам форматування та стилю. Ви можете налаштувати деякі IDE так, щоб вони автоматично запускали Ruff під час збереження, що може полегшити цей процес.

Майте на увазі, що найважливішою частиною PEP 8 є Розділ 0: «Безглузда послідовність — це привид обмежених умів». Існують ситуації, коли дотримання PEP 8 не має сенсу, і важливо розуміти, що в відповідних випадках цілком прийнятно, а іноді навіть бажано, писати код, який не відповідає переліченим правилам. Знати, коли можна відхилятися від цих правил, так само важливо, як і дотримуватися їх у більшості випадків.

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

Ми дотримуємося американських правил правопису при назві 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():
 """Тестовий docstring виглядає так (#123456)."""