Como mejorar la presentación de mi código sin ser un experto en python

TL;DR Muchas veces escribimos código que mucho después debemos revisar y no podemos entender nada de lo que hemos hecho, muchas veces ya hemos aprendido mucho mas y siempre es buena idea refactorizar dicho código, aprenderemos a como mejorar nuestro código sin ser expertos, de manera que al volver a el refactorizar no sea una pesadilla, o incluso evitar rehacer todo por completo

 Si no todos hablamos ingles, ¿pero que se hace?

Si, esto es lo primero que muchas veces le digo a los hispanoparlantes (o incluso una que otra vez a compañeros de Brazil de mi equipo), y es que aunque nos duela por no desarrollar en nuestra lengua madre, es mucho mejor escribir todo nuestro código en ingles, sobretodo si nuestro equipo es pluricultural o algún día llegara a serlo, o si desarrollamos una librería que otra persona utilizará. Además, hay otras anotaciones que debemos tener en cuenta:

  • Muchas veces en el español, o el portugués queremos crear variables con palabras conocidas en nuestra lengua, pero llevan letras que no podemos utilizar para nombrar nuestras variables, el ejemplo típico es la palabra “año”, que si no utilizamos ñ podríamos dejar una “mala palabra” en nuestro código, otra manera en que muchos desarrolladores abordan este problema es usar una h en la mitad de la palabra “anho” lo cual dificulta la fácil lectura del código.
  • Otra razón es evitar el “poliglotismo” en el código, muchas veces nos hemos encontrado con líneas de código en español e ingles, el mismo lenguaje de programación nos obliga a escribir código en ingles, de otra manera el código se vuelve un entrelazado de idiomas que no es muchas veces agradable para la vista (sobretodo para reclutadores de nuestra área).
  • Por ultimo, que mejor manera de mejorar tu ingles sin cursos, muchas veces nos encontraremos con palabras que debemos usar y que tenemos que buscar su traducción, muchas veces nos aprendemos esa palabra de tanto utilizarla en el código (por ejemplo, usar mucho la palabra “tax” para referirte a cada vez que haces calculo de impuestos, se quedará en tu cabeza, lo se)

Las variables son muy importantes, ¡dales su valor!

He encontrado muchas veces (y lo he hecho, soy culpable) es nunca saber como llamar una variable, y terminar colocando un nombre el cual a futuro es muy difícil de recordar, aquí te dejo mis consejos:

  • Nunca utilices acrónimos o siglas, a menos que sean muy comunes evita todas las siglas, muchas veces se nos ocurre para acortar los nombres de las variables, pero esto lo que hace es dañar la “legibilidad” de tu código.
  • Las variables siempre en ingles, no voy a entrar en detalles ya que hablamos de esto en el apartado anterior.
  • Respeta las convenciones, en python las variables siempre son escritas en “minúscula” y si necesitamos mas de una palabra en su nombre (recuerda nada de siglas) podemos utilizar un guion bajo ( _ ) entre las palabras.
  • Intenta acortar (no con siglas) las variables hasta lo mínimo posible, sin dañar su legibilidad, por ejemplo, si tienes una variable “State import taxes” y puedes acortar como import_taxes, o state_taxes sin perder legibilidad hazlo, pero si es importante diferenciar que impuesto es, ya que en el mismo bloque de código tienes varios taxes, no recortes la variable, úsala completa state_import_taxes.

Las funciones son lo máximo, úsalas cada que puedas, pero documenta que hacen

Lo se, yo también paso por eso, muchas veces escribimos funciones y olvidamos documentar que hacen, y cuando volvemos a ellas, siempre será necesario depurar nuestro código para recordar que hace. Por ello es bueno siempre dejar así sea lo mínimo de documentación, como que es cada entrada y una pequeña descripción de que hace la función y que retorna, por ejemplo:

def calculate_import_state_tax(price, state, type):
    """Return the state taxes applied to the price added to the initial price"""
    # Do your stuff
    return price + (tax * price)

Solo con esta línea sabremos que retorna la función, y no confundiremos si retorna el valor del precio total o solo el impuesto aplicado al precio, y hacer luego malos cálculos dentro de nuestra implementación de la función.

Otra cosa importante en las funciones es que al igual que las variables, es necesario que su nombre nos ayude a entender que hace, además aplicaremos lo que comentamos en el anterior punto, nombres en ingles, nombres con sentido, sin siglas, etc.

Da un poco de aire a tu código

Si, así como lees, muchas veces escribimos una cantidad de código abrumadora y no separamos las funciones de las clases para dar un respiro entre ellas, o la inicialización de atributos iniciales, incluso separar un poco las funciones matemáticas ayudan a su lectura, si revisamos la documentación sobre el PEP8, hay muchos apartados que hablan sobre esto, por ejemplo:

  • Separar con 2 líneas en blanco, la definición de la clase y las funciones y sus atributos por defecto.
  • Separar con 1 línea en blanco las funciones internas de una clase.
  • Incluso es bueno separar por 1 línea en blanco las líneas y/o funciones que sean parte de una misma lógica, así será mas fácil identificar cada paso dentro de nuestro código

Otro ejemplo es separar las funciones matemáticas o definiciones de variables:

  • Utiliza un espacio antes y después de un igual ( = ) en la definición de una variable
  • De la misma manera que con el igual ( = ) es bueno dividir los signos matemáticos en las expresiones matemáticas referentes a sumas y restas ( +, – ) o multiplicación y división si las sumas y restas están agrupadas por paréntesis.
  • Utiliza los paréntesis cada vez que veas conveniente separar las operaciones, esto ayuda visualmente a leer dicha operación
  • Si una operación se extiende mucho, divide cada una de las partes de la operación en una variable diferente, y luego únelas en la función principal.

Ahora, es importante no abusar de dar un poco de aire a nuestro código, aunque se vea un poco mas ordenado colocar los iguales ( = ) de las diferentes variables al mismo nivel, no es una buena practica.

Si:
a = 1
b = 2
this_is_long = 3
No: 
a            = 1
b            = 2
this_is_long = 3

 

Siempre retorna algo de tus funciones

Muchas veces olvidamos retornar algo desde nuestras funciones (que no sea error claro) y nos encontramos con errores por intentar realizar operaciones con un “None”, y en ese momento se nos vuelve necesario volver a dicha función y depurar para poder entender por que se retorna None, entonces es mejor ser un poco mas explicito, de manera que una vez al revisar la función entendamos su comportamiento, por ello siempre te recomiendo retornar None de manera explicita, y tal vez documentar un poco por que esta situación se da, (Por ejemplo, faltó un parámetro y no se pudo realizar alguna validación, y se retorna None con un comentario de esta manera si alguna vez llegamos a ese punto y nos da error sepamos por que aconteció).

 

Bueno espero les haya gustado este post, fue bastante corto pero son mis primeras recomendaciones para mejorar la legibilidad de nuestro código sin necesidad de ser un experto en Python, también le recomiendo leer un poco sobre el PEP-8 y el artículo The Zen of Python para que veas como seguir mejorando tu código y su legibilidad.

¡Hasta luego! 🙂