Guía de estilo de código

Esta guía incluye información y directrices para escribir código para BeeWare.

Estilo de código

BeeWare sigue PEP 8 en nuestro código base, excepto que la longitud de línea se ha ampliado de 79 a 88 caracteres. Utilizamos Ruff para aplicar las convenciones PEP 8 siempre que sea posible. Cuando confirmes tu código, pre‐commit ejecutará comprobaciones, incluyendo Ruff. Siempre que sea posible, esto formateará automáticamente tu código para garantizar que cumple con nuestros estándares de formato y estilo. Puedes configurar algunos IDE para que ejecuten automáticamente Ruff al guardar, lo que puede ayudar en el proceso.

Ten en cuenta que la parte más importante de PEP 8 es Sección 0: La Consistencia Tonta es el Duende de las Mentes Pequeñas. Hay situaciones en las que ser consistente con PEP 8 no tiene sentido, y es importante entender que, cuando sea aplicable, es aceptable, y a veces preferible, escribir código que no esté en línea con las reglas listadas. Saber cuando ser inconsistente con esas reglas es tan importante como mantener la consistencia en la mayoría de las situaciones.

Esto se refleja, por ejemplo, en las convenciones de nomenclatura. Las bibliotecas de BeeWare suelen necesitar interactuar con otros lenguajes. Al crear envoltorios para otros lenguajes, es recomendable (y, en algunos casos, obligatorio) seguir las convenciones de nomenclatura del lenguaje de destino, en lugar de las de Python. Por ejemplo, al invocar o hacer referencia a código Java, las funciones deben seguir la convención de Java de mixedCase, en lugar de la recomendada por PEP 8 de snake_case.

Seguimos la ortografía estadounidense para la denominación de API, variables, etc.

Además, hay algunas adiciones específicas de BeeWare a la PEP 8:

Desglosas invocaciones a funciones largas

Cuando una función invoca con más de un argumento que no cabe en una sola línea, coloca cada argumento en una propia línea separada y añade una coma al final del último argumento. Ruff permite (y sugerirá) un formato de múltiples argumentos sobre una línea envuelta:

my_function(
    arg1, arg2, arg3
)

Este estilo no sería utilizado. En su lugar, distribuye los argumentos de uno por línea añadiendo una coma al final del último argumento:

my_function(
    arg1,
    arg2,
    arg3,
)

Desglosa cadenas largas

Cuando debe desglosar un argumento de cadena en varias líneas para cumplir con los requisitos de longitud de línea, cubre los literales de cadena concatenados entre paréntesis para que quede claro que la cadena es un único argumento. Es decir, preferimos:

my_function(
    (
 "esta es una cadena muy larga"
 "que se divide en dos líneas"
    ),
    segundo_argumento,
)

sobre:

my_function(
    "esta es una cadena muy larga"
    "que se divide en dos líneas",
    second_argument,
)

Lo que hay que evitar

Intentamos evitar los módulos utils tanto como sea posible, con comprender que algunas veces son inevitables. La alternativa preferible es encontrar un lugar para la prestación en donde esté en el código fuente, en lugar de utilizar un módulo utils.

Como regla general, intentamos evitar o aplazar cualquier código de inicialización costoso, con el fin de lograr un inicio más rápido de la aplicación. Por ejemplo, los módulos del paquete toga-core se cargan de forma diferida, es decir, solo se importan cuando se solicitan, en lugar de hacerlo por adelantado. Esto acelera el inicio y solo se dedica tiempo a lo que la aplicación está utilizando realmente.