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 no nosso código base, exceto com o 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 faz uma submissão do seu código, a pre-submissão executa verificações, incluindo o Ruff. Sempre que possível, isso formata automaticamente o seu código para garantir que ele vai ao encontro das nossas normas de formatação e estilo. Pode configurar alguns IDEs para executar automaticamente o Ruff ao salvar, o que pode ajudar no processo.

Lembre-se que a parte mais importante da PEP 8 é a Secção 0: Uma Consistência de Tolos é o Bicho-Papão das Mentalidades Limitadas. 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:

Embora a anotação de tipos em conformidade com a PEP 484 seja opcional, ela continua sendo fortemente recomendada, especialmente em todas as interfaces de API públicas.

Segue abaixo um exemplo de definição de função normalizada com indicações de tipo adequadas e uma string de documentação do Sphinx:

def nome_da_função(param1: int, param2: str) -> bool:
"""Exemplo de função com tipos e uma string de documentação.

:param param1: O primeiro parâmetro.
:param param2: O segundo parâmetro.

:returns: O valor de retorno. True em caso de sucesso, False caso contrário.
"""

Dividir chamadas de função longas¶

Quando uma chamada de função com mais de um argumento não couber numa única linha, coloque cada argumento numa 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 numa linha por cada um, adicionando uma vírgula no final do último argumento:

my_function(
    arg1,
    arg2,
    arg3,
)

Dividir strings longas¶

Quando uma string argumento precisar ser dividida 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(
    (
        "esta é uma string longa "
        "que está partida em duas linhas"
    ),
    segundo_argumento,
)

sobre:

my_function(
    "esta é uma string muito longa"
    "que se estende por duas linhas",
    segundo_argumento,
)

Coisas a evitar¶

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 noutra 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 da aplicação. 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 apenas gasta tempo com o que a aplicação está realmente a usar.

Ao escrever comentários, evite o uso de pronomes na primeira pessoa do plural, tais como “nós” (por exemplo, escreva “Faz um loop” em vez de “Nós fazemos um loop”).

Nas descrições dos testes, indique o comportamento esperado que cada teste demonstra. Não inclua introduções como “Testa se” ou “Assegura que”.

Reserve as referências a bilhetes para questões pouco conhecidas, nas quais o bilhete contenha detalhes adicionais que não possam ser facilmente descritos em strings documento ou comentários. Inclua o número do bilhete no final de uma frase, desta forma:

def test_foo():
 """Uma string de documentação de teste tem este formato (#123456)."""