Código Python limpio: comentarios, docstrings y PEP 8
Esta lección es una traducción del original en inglés.Read in EnglishAvisar de un error de traducción
Imagina que abres un libro de cocina en el que cada receta está garabateada con mala letra, sin títulos, sin lista de ingredientes y sin espacio entre los pasos. Podrías descifrarlo con el tiempo, pero sería un suplicio. Con el código pasa lo mismo.
Los programadores profesionales pasan mucho más tiempo leyendo código que escribiéndolo. Algunos estudios sugieren que la proporción es de unos 10 a 1. Por eso, hacer que tu código sea fácil de leer es una de las habilidades más valiosas que puedes aprender.
En este tutorial aprenderás a escribir código Python que otras personas (y tu yo del futuro) disfruten de verdad al leer. Veremos los comentarios, los docstrings, las convenciones de nombres y PEP 8, la guía de estilo oficial de Python.
¿Por qué importa el código limpio?
Piensa en una habitación desordenada. Sabes que tus cosas están ahí, en algún sitio, pero encontrar algo te lleva una eternidad. El código limpio es como una habitación ordenada: cada cosa tiene su lugar y encuentras rápido lo que necesitas.
Si escribes código hoy y vuelves a él dentro de dos semanas, habrás olvidado qué hace la mitad. Un código claro y bien organizado funciona como un mapa para tu yo del futuro.
El código limpio también importa cuando trabajas con otras personas. En un equipo, todos necesitan entender el código de los demás. El código desordenado frena a todo el equipo.
314.159 Area of circle: 314.159
Las dos versiones calculan lo mismo. Pero la versión B te dice qué hace el código sin necesidad de más explicaciones. Los nombres de las variables son la documentación.
Cómo escribir buenos comentarios en Python
Ya sabes que los comentarios empiezan con # y que Python los ignora. Pero saber cuándo y cómo usarlos es lo que distingue el código de un principiante del código profesional.
Un buen comentario explica por qué se hace algo, no qué hace el código. Si tu código es lo bastante claro, el "qué" debería verse con solo leerlo.
# Set x to 5
x = 5
# Add 1 to x
x = x + 1
# Print x
print(x)# Start with 5 retries (server sometimes drops first request)
retry_count = 5
# Move to next attempt
retry_count = retry_count + 1
print(retry_count)¿Notas la diferencia? Los malos comentarios repiten lo que el código ya dice. Los buenos te cuentan por qué existe el código y te dan un contexto que el código por sí solo no te da.
¿Cuándo conviene agregar comentarios al código Python?
Agrega un comentario cuando el código hace algo sorprendente o poco evidente. Si alguien que lee tu código diría "espera, ¿por qué?", ahí es donde va un comentario.
(sin salida)
Usa también los comentarios para notas TODO: recordatorios de cosas que piensas corregir o mejorar más adelante. La mayoría de los editores de código resaltan los comentarios TODO para que sean fáciles de encontrar.
¿Cuándo es mejor evitar los comentarios?
Si sientes la necesidad de escribir un comentario que explique qué hace el código, suele ser señal de que el propio código debería ser más claro. A menudo, con mejores nombres de variables ya no hace falta ningún comentario.
# Calculate the final price with 20% discount
p = x - (x * 0.2)discount_rate = 0.20
final_price = original_price - (original_price * discount_rate)¿Qué son los docstrings en Python?
Un docstring es una cadena especial que describe qué hace una función, una clase o un módulo. Va justo al principio del cuerpo de la función, entre comillas triples (""").
Piensa en un docstring como el manual de instrucciones que viene con un producto. No necesitas abrir el producto para saber qué hace: te basta con leer el manual.
Tip: $10.00
Help on function calculate_tip in module __main__:
calculate_tip(bill_amount, tip_percent)
Calculate the tip amount for a restaurant bill.
Args:
bill_amount: The total bill in dollars.
tip_percent: The tip percentage (e.g., 20 for 20%).
Returns:
The tip amount in dollars.Cuando llamas a help() con una función, Python muestra su docstring. Así es también como las funciones integradas como print() y len() muestran su documentación.
Para funciones cortas y sencillas basta con un docstring de una línea. En las funciones más complejas, describe los argumentos y lo que devuelve la función.
49 144
Convenciones de nombres en Python: cómo nombrar variables
Elegir buenos nombres es una de las partes más difíciles de programar. Un buen nombre de variable es como una buena etiqueta en una caja de almacenaje: sabes exactamente qué hay dentro sin abrirla.
Python usa un estilo llamado snake_case para los nombres de variables y funciones. Las palabras van en minúsculas y separadas por guiones bajos.
User: Alice Total: $29.99 Logged in: True Max retries: 3
Estas son las principales convenciones de nombres que siguen los programadores de Python:
Player score: 100 Max speed: 120 Pi: 3.14159
Cómo elegir nombres de variables con significado
El nombre de una variable debe describir lo que el valor representa, no de qué tipo es. El objetivo es que tu código se lea como una frase.
x = "Alice"
n = 25
f = True
temp = 3
data = 98.6
my_list = ["math", "science"]student_name = "Alice"
student_age = 25
is_enrolled = True
max_attempts = 3
body_temperature = 98.6
course_list = ["math", "science"]Los nombres de una sola letra como x, n e i están bien en fórmulas matemáticas cortas o en bucles pequeños. Pero para todo lo demás, usa un nombre de verdad que explique para qué sirve.
¿Qué es PEP 8? Lo básico de la guía de estilo de Python
PEP 8 es la guía de estilo oficial de Python. PEP significa "Python Enhancement Proposal" (propuesta de mejora de Python), y la número 8 es la que trata del estilo al escribir código. Es como un código de vestimenta para el código Python: todos siguen las mismas reglas, así que cualquier código Python te resulta familiar.
No necesitas memorizar todas las reglas. Estas son las que más importan cuando estás empezando.
Cómo usar la indentación en Python (4 espacios)
Python usa la indentación para agrupar el código. Lo estándar son 4 espacios por nivel. Nunca mezcles tabuladores y espacios: elige uno (los espacios) y no lo cambies.
Hello, Alice! Hello, stranger!
Cómo usar las líneas en blanco en el código Python
Las líneas en blanco son como los cambios de párrafo en una redacción. Separan ideas distintas y hacen que tu código sea más fácil de recorrer con la vista.
Area: 15 Perimeter: 16
Usa dos líneas en blanco antes y después de las definiciones de funciones del nivel superior. Usa una línea en blanco para separar las secciones lógicas dentro de una función.
Cómo usar espacios alrededor de los operadores en Python
Pon un espacio a cada lado de operadores como =, +, -, == y !=. Así tu código se lee mucho mejor de un vistazo.
total=price*quantity+tax
is_valid=age>=18 and name!=""
result=x**2+y**2total = price * quantity + tax
is_valid = age >= 18 and name != ""
result = x**2 + y**2Errores de estilo comunes en Python y cómo corregirlos
Veamos los errores de estilo más comunes que cometen los principiantes y cómo corregirlos. Son cambios pequeños que mejoran mucho la legibilidad.
if is_active == True:
print("Active")
if result == None:
print("No result")if is_active:
print("Active")
if result is None:
print("No result")No compares con True o False usando ==. Usa la variable directamente. Con None, usa siempre is None en lugar de == None.
userName = "Alice" # camelCase
total_Price = 29.99 # mixed style
def CalculateTotal(): # PascalCase for function
passuser_name = "Alice" # snake_case
total_price = 29.99 # snake_case
def calculate_total(): # snake_case
passElige un estilo y sé coherente. En Python, ese estilo es snake_case para variables y funciones. Mezclar estilos hace que tu código parezca caótico.
def add(a, b):
return a + b
def subtract(a, b):
return a - b
def multiply(a, b):
return a * bdef add(a, b):
return a + b
def subtract(a, b):
return a - b
def multiply(a, b):
return a * bLinters de Python: herramientas que revisan tu estilo automáticamente
No tienes que memorizar todas las reglas de PEP 8. Unas herramientas llamadas linters pueden revisar automáticamente si tu código tiene problemas de estilo. Piensa en un linter como un corrector ortográfico, pero para el estilo del código.
Estos son los linters de Python más populares:
La mayoría de los editores de código (como VS Code) pueden ejecutar linters en segundo plano y subrayar los problemas de estilo mientras escribes. Es como tener a un entrenador de estilo sentado a tu lado.
Ejercicios de práctica
¡Hora de practicar! Estos ejercicios te ayudarán a adquirir el hábito de escribir código Python limpio y legible.
Escribe una función llamada celsius_to_fahrenheit que reciba una temperatura en grados Celsius y devuelva el valor en Fahrenheit.
La fórmula es: fahrenheit = celsius * 9/5 + 32
Tu función debe incluir:
Después, imprime el resultado de convertir 100 grados Celsius. La salida debe ser:
212.0Este código funciona, ¡pero los nombres de las variables son pésimos! Nadie sabe qué significan x, y, z y a.
Cambia el nombre de las variables para que tengan significado y usa snake_case. El código calcula el sueldo semanal de un trabajador. La salida debe quedar exactamente igual:
Weekly pay: $450.0
With overtime: $562.5El código de abajo está desordenado. Reescríbelo siguiendo las reglas de PEP 8:
def calcArea(W,H):
result=W*H
return result
def calcPerimeter(W,H):
result=2*(W+H)
return result
w=8
h=5
print(f"Area: {calcArea(w,h)}")
print(f"Perimeter: {calcPerimeter(w,h)}")Corrige estos problemas:
La salida debe ser:
Area: 40
Perimeter: 26Esta función funciona, pero está desordenada. Refactorízala para que quede limpia y profesional:
def d(p,r):
a=p*r/100
t=p-a
return t
print(d(200,15))Tu versión refactorizada debe:
La salida debe ser:
170.0Resumen: lo que aprendiste sobre código Python limpio
Ya conoces los hábitos que distinguen el código de un principiante del código profesional. Aquí tienes una referencia rápida:
| Concepto | Regla clave | Ejemplo |
|---|---|---|
Comentarios (#) | Explica el porqué, no el qué | # Texas tax rate (8.25%) |
Docstrings (""") | Describe lo que hace una función | """Convert Celsius to Fahrenheit.""" |
| Nombres de variables | Descriptivos, en snake_case | total_price, is_valid |
| Constantes | UPPER_SNAKE_CASE | MAX_SPEED = 120 |
| Indentación | Siempre 4 espacios | def greet(): y luego 4 espacios |
| Líneas en blanco | 2 entre funciones | Separan las secciones lógicas |
| Operadores | Espacios alrededor de =, +, etc. | x = a + b |
| PEP 8 | La guía de estilo oficial de Python | La coherencia manda |
Escribir código limpio no consiste en lucirse. Consiste en ser amable con tus compañeros de equipo, con tu yo del futuro y con cualquiera que lea tu código. Empieza a crear estos hábitos ahora y te servirán durante toda tu carrera en la programación.
¿Qué sigue?
¡Terminaste la sección de fundamentos de Python! Ya tienes una base sólida de lo esencial de Python. A continuación pasarás al control de flujo, donde aprenderás a hacer que tus programas tomen decisiones con instrucciones if y repitan acciones con bucles.