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:

Dividir llamadas a funciones largas

Cuando una llamada a una función con más de un argumento no cabe en una sola línea, coloca cada argumento en una línea separada y añade una coma al final del último argumento. Ruff permite (y sugerirá) un formato en el que varios argumentos se escriben en una sola línea con saltos de línea:

my_function(
    arg1, arg2, arg3
)

No se debe utilizar este estilo. 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,
)

Dividir cadenas largas

Cuando sea necesario dividir un argumento de cadena en varias líneas para cumplir con los requisitos de longitud de línea, envuelve los literales de cadena concatenados entre paréntesis para que quede claro que la cadena es un único argumento. Es decir, 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,
)

Lo que hay que evitar

Intentamos evitar los módulos utils en la medida de lo posible, aunque a veces son inevitables. La alternativa preferible es encontrar un lugar para la función 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.