Guia de estilo de código

Este guia inclui informações e diretrizes para escrever código para BeeWare.

Estilo de código

O BeeWare segue a PEP 8 em nossa base de código, exceto pelo comprimento da linha, que foi expandido de 79 para 88 caracteres. Usamos o Ruff para aplicar as convenções do PEP 8 sempre que possível. Quando você faz o commit do seu código, o pre-commit executa verificações, incluindo o Ruff. Sempre que possível, isso formata automaticamente o seu código para garantir que ele atenda aos nossos padrões de formatação e estilo. Você pode configurar alguns IDEs para executar automaticamente o Ruff ao salvar, o que pode ajudar no processo.

Tenha em mente que a parte mais importante da PEP 8 é a Seção 0: A Foolish Consistency is the Hobgoblin of Little Minds. Há situações em que permanecer consistente com a PEP 8 não faz sentido, e é importante entender que, quando aplicável, é aceitável, e às vezes preferível, escrever código que não esteja alinhado com as regras listadas. Saber quando ser inconsistente com essas regras é tão importante quanto manter a consistência na maioria das situações.

Uma manifestação disso pode ser observada nas convenções de nomenclatura. As bibliotecas BeeWare frequentemente precisam fazer a ponte com outras linguagens. Ao criar wrappers para outras linguagens, é recomendável (e, em alguns casos, obrigatório) seguir as convenções de nomenclatura da linguagem de destino, em vez das do Python. Por exemplo, ao chamar ou referenciar código Java, as funções devem seguir a preferência do Java por mixedCase, em vez da preferência da PEP 8 por snake_case.

Seguimos a ortografia dos EUA para nomear APIs, variáveis, etc.

Há também algumas adições específicas do BeeWare à PEP 8:

Divisão de chamadas de função longas

Quando uma chamada de função com mais de um argumento não couber em uma única linha, coloque cada argumento em uma linha separada, com uma vírgula no final do último argumento. O Ruff permite (e sugere) um formato com vários argumentos em uma única linha quebrada:

my_function(
    arg1, arg2, arg3
)

Este estilo não deve ser usado. Em vez disso, distribua os argumentos em uma linha por cada um, adicionando uma vírgula no final do último argumento:

my_function(
    arg1,
    arg2,
    arg3,
)

Dividir strings longas

Quando um argumento de string precisar ser dividido em várias linhas para atender aos requisitos de comprimento de linha, coloque os literais de string concatenados entre parênteses para que fique claro que a string é um único argumento. Ou seja, preferimos:

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

sobre:

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

Coisas a serem evitadas

Tentamos evitar os módulos "utils" o máximo possível, com o entendimento de que, às vezes, eles são inevitáveis. A alternativa preferida é encontrar um lugar para o recurso em outra parte do código-fonte, em vez de usar um módulo utils.

Como regra geral, tentamos evitar ou adiar qualquer código de inicialização caro, a fim de obter uma inicialização mais rápida do aplicativo. Por exemplo, os módulos no pacote toga-core são “carregados de forma preguiçosa” — eles só são importados quando solicitados, em vez de todos de uma vez. Isso acelera a inicialização e gasta tempo apenas com o que o aplicativo está realmente usando.