Quizas, sea un aspecto poco valorado de la programación, pero cuando la magnitud del software que escribes se incrementa, tener unas guías de estilo al programar facilitan la vida, tanto la tuya propia cuando meses después tienes que revisar código propio, cómo revisar el código de otros.
En este aspecto, Python ha sido siempre consciente de esto y existe una guía de estilos recomendada. Aquí van las más importantes:
Docstrings
Son las cadenas de documentación, y van siempre entre triples comillas “”” docstring “””. Es importante que estén en estos tres sitios:
- Al principio de cada fichero, describiendo lo que hace cada módulo
- Debajo de la inicialización de cada clase, para describir lo que hace dicha clase
- Debajo de cada funcón, para describir lo que hace dicha función
Se trata de describir lo que hace, no cómo se hace. En el caso de las funciones, es fundamental explicar lo que hace la función, los argumentos que necesita, y la salida que produce.
Los docstrings son importantes porque existen muy buenas herramientas para automatizar la documentación de software, por lo que es un aspecto que debería cuidarse por parte del desarrollador.
Comentarios
Los comentarios deben usarse para describir cómo una sección de un código hace o ejecuta algo, poniendo énfasis en no comentar lo evidente. Sí deberia de comentarse el porqué de algunas decisiones, o sobre algún fragmento de código particular.
Los comentarios van precedidos por #, y no hay que confundir los comentarios que se iniciar con “”” texto “””, que están, porque eso no son comentarios, sino una cadena en mitad del código!
Variables globales
Deben evitarse a toda costa, y hacerlo constituye una buena práctica (no siempre es posible, claro! pero al menos, evitarlo en todo lo posible).
La única excepción son las constantes, que no existen en Python y se terminan declarando como variables, que además van siempre en mayúscula.
Indentación
La indentación en Python necesita ser consistente, siempre la misma: o tabulador o espacios, pero siempre la misma. Es preferible 4 espacios.
Nombres de variables
Las variables deben tener al menos siempre 3 caracteres, y el primero de ellos debe cumplir:
- Siempre empiezan en minúscula, excepto las constantes, que lo hacen en mayúsculas
- Las funciones y los métodos siempre empiezan por minúscula
- En las clases, siempre se empieza en mayúscula
También es muy buena práctica no incluir en el nombre de las variables ningun carácter en mayúscula, es decir, todo en minúsculas, y en caso necesario, usar guiones bajos, como nueva_variable.
Campos de las clases
Los campos de las clases y de las instancias no deben ser accesibles nunca directamente. Esto es, deberían de empezar todos por guión bajo, y disponer de métodos para recuperar su valor: si los datos de un campo son requeridos dese fuera, debe crearse métodos.
Quizás, este sea el punto más “extraño”, puesto que en otros lenguajes sí se usan propiedades públicas.
Ámbito
El ámbito de las variables es importante, y no deben duplicarse nombres de variables con distintos ámbitos. En cualquier caso, prevalece la más cercana. Así que, cuidado con la definición de variables.
Argumentos y variables
Aunque no hay un número máximo establecido, sí que es importante ajustarse al menor número posible de ellos, sobre todo para no complicar en exceso el código.
Por último ….
Hay una regla fundamental en Python, y es:
Diseña tus funciones para que hagan solo 1 cosa, pero que la hagan bien
Lee bien esta entrada y ve poniéndola en práctica, poque es posible que en un futuro te arrepientas de no haber seguido esta guía, y si no … al tiempo!