Óscar Ramírez Jiménez - Python a fondo

• Los comentarios deben de estar compuestos de una o varias frases completas, terminar con un punto al final y comenzar con mayúsculas, a no ser que comiencen con un identificador que esté en minúscula, en ese caso, se respetará siempre la forma en que esté escrito el identificador.

• Para programadores de habla distinta a la inglesa, se ruega que escriban los comentarios en inglés a no ser que estén 120 % seguros de que cualquier otro desarrollador que lea el código sabrá su idioma.

• Los bloques de comentarios afectan al código que está indentado al mismo nivel que el bloque de comentarios, y entre párrafo y párrafo habrá que añadir dos líneas en blanco.

• Los comentarios de una sola línea deberán usarse de forma moderada, los añadidos tras la línea de código se harán añadiendo dos espacios, los caracteres "# " detrás de la línea en la que se desea añadir el comentario y solo se añadirán si el objetivo de la línea de código no es obvio en sí mismo.

• Para la documentación de código (docstrings) se utilizarán siempre los tres caracteres seguidos """ para abrir y cerrar el bloque de comentarios.

• Los módulos públicos, funciones, clases y métodos deben tener un docstring (documentación de código) y solo los métodos privados pueden no tenerlo, aunque deben tener un comentario justo después de la definición de la cabecera del mismo.

La convención de nombres establece cómo deben de nombrarse los identificadores de cada parte del lenguaje (variables, funciones, nombres de fichero, clases, etc.). PEP-8 define también las reglas para nombrar el código Python.

Antes de pasar a las reglas se exponen las convenciones más usadas:

• CamelCase:se construye uniendo palabras clave una detrás de otra, pero utilizando la primera letra de cada palabra en mayúscula. Su nombre hace referencia a que el resultado final se asemeja a la joroba de los camellos.

• snake_case:se construye uniendo las palabras con una barra baja (_) entre ellas.

• SCREAMING_SNAKE_CASE:se construye de forma similar a la snake_case, pero usa todos los caracteres en su forma mayúscula.

• Mayúsculas o minúsculas:son palabras en las que todas las letras son de uno u otro formato.

A continuación, se muestra cómo se usan estas convenciones de nombres en Python:

• Los nombres deberían estar definidos por el uso que se vaya a hacer de ellos y no por la implementación interna.

• Si un proyecto ya tiene una convención de nombres establecida, se mantendrá, dado que no hay que romper la consistencia del proyecto por seguir la guía de estilos.

• Para definir que un objeto está protegido se añade un carácter "_" como prefijo del nombre, dado que al hacer una importación general (utilizando el carácter *) se omiten los nombres escritos de esta forma.

• Los nombres que terminan con el carácter "_" se utilizan para evitar conflictos con palabras reservadas como class, def, if, etc.

• Cuando un nombre comienza por doble"_" (por ejemplo: __foo) dentro de cualquier clase (por ejemplo, Bar), se trata de manera diferente, dado que el compilador lo cambiará internamente por _ clase>__ (_Bar__foo en el ejemplo), lo que se conoce como Python's mangling rules y evita colisiones de nombres. Este método se asemeja a hacer un objeto privado, aunque realmente se puede acceder a él si se conocen las reglas, las clases y el nombre de la función. En cualquier caso, se recomienda encarecidamente no acceder a estos métodos utilizando este tipo de nombres.

• Si el nombre de la función comienza y termina con doble"_", se considera un método mágico y se recomienda que no se inventen nuevos nombres, sino que se usen los disponibles en la documentación.

• Para nombrar paqueteso módulosse utilizarán nombres en minúsculas o snake_case, intentando que sean lo más cortos posible.

• Para los nombres de las clasesy los tipos de variablesse usa CamelCase.

• El primer parámetro para los métodos de instancias y para los métodos de clase será self y cls, respectivamente.

• Para los nombres de las funcionesse utilizará snake_case. Prefijo con un solo "_" si la función es local al módulo y prefijado con 2 caracteres "_" solo para evitar colisiones con la herencia al hacer uso de las Python's mangling rules .

• Para las constantesse hará uso de las mayúsculas o de SCREAMING_SNAKE_CASE.

Las recomendaciones son simples y fáciles de seguir, pero siempre es mejor poder disponer de un software que compruebe este tipo de estilos y alerte al usuario en caso de que alguna regla haya sido infringida y le sugiera cómo se podría arreglar.

Para este propósito, en Python existen analizadores de código que comprueban si se ha incumplido alguna de las reglas establecidas por la PEP-8 en un código. Suelen marcar qué regla ha sido infringida, la línea exacta y, en muchas ocasiones, ofrecen alternativas de código para que este cumpla con las reglas. El programa más utilizado es Pylint( https://www.pylint.org/), que no solamente comprueba si la sintaxis cumple con las reglas de PEP-8, sino que también alerta de posibles problemas en el código, ayuda a hacer refactorizaciones, se integra fácilmente con editores y es capaz de hacer diagramas UML que describen la estructura del código de una forma estándar.

Cuando se pretende comprobar si un módulo cumple las reglas de estilos, se puede utilizar el paquete pycodestyle( https://github.com/PyCQA/pycodestyle), el cual se puede ejecutar por consola para obtener un reporte detallado del estado del módulo analizado.

Cabe destacar que la mayoría de editores modernos tienen soporte para Pylint o disponen de su propio validador, que en la mayoría de ocasiones viene activado por defecto y, en algunos casos, puede aplicar los cambios sugeridos automáticamente, aunque es recomendable revisar ese tipo de cambios para no tener cambios de código no deseados.

Intentando crear una guía para resolver los conflictos de cómo se debería escribir código Python, en el año 1999, Patrick Phalen pidió a Tim Peters y a Guido van Rossum en la lista general de Python ( python-list@python.org) que hicieran una lista de unas 20 reglas que todo pythonista debería seguir para discernir la forma en la que habría que proceder ante un conflicto a la hora de escribir código pythónico.

El pythonista que tomó la iniciativa y propuso las primeras 19 fue Tim Peters. Dejó espacio para que Van Rossum añadiese una más y completase hasta 20 las reglas, pero hasta la fecha esto no ha ocurrido (ni se espera que ocurra).

La PEP que recoge esta lista de reglas fue bautizada como PEP-20 y es accesible tanto por el método habitual (en la página web oficial, https://www.python.org/dev/peps/pep-0020/) como haciendo uso del huevo de pascua incluido en todas las versiones de Python, simplemente ejecutando el siguiente comando en la consola interactiva:

En castellano sería algo como:

• Bonito es mejor que feo.

• Explícito es mejor que implícito.

• Simple es mejor que complejo.

• Complejo es mejor que complicado.