Cómo escribir código limpio, legible y mantenible

Escribir código no es solo una tarea de programación; también es un arte. Un buen código debe ser limpio, legible y fácil de mantener.

En este artículo, te mostraremos cómo lograr que tu código cumpla con estos requisitos esenciales y, al mismo tiempo, compartir ejemplos didácticos que facilitarán tus esfuerzos por mejorar la calidad de tu código.

1. Nomenclatura consistente y descriptiva

Un nombre claro y descriptivo facilita la comprensión del propósito de una variable, función o clase. Un buen nombre responde a la pregunta, ¿qué hace o representa esto?

Prefiere nombres completos en lugar de abreviaturas.

Utiliza verbos para nombres de funciones y sustantivos para nombres de variables y clases.

Ejemplo en Python:

import math

def calcular_area_circulo(radio):
    """
    Esta función calcula el área de un círculo dado su radio.

    Parámetros:
    radio (float): El radio del círculo.

    Retorna:
    float: El área del círculo.
    """
    area = math.pi * radio ** 2
    return area

def main():
    """
    Función principal que solicita al usuario el radio del círculo,
    calcula su área e imprime el resultado.
    """
    try:
        radio = float(input("Ingrese el radio del círculo: "))
        area = calcular_area_circulo(radio)
        print("El área del círculo con radio {} es {:.2f}".format(radio, area))
    except ValueError:
        print("Error: Por favor ingrese un número válido.")

if __name__ == "__main__":
    main()

Este código utiliza nombres de variables y funciones descriptivos que hacen que el código sea fácil de entender y mantener. Además, incluye comentarios que explican la funcionalidad de cada parte del código.

2. Evita el anidamiento excesivo de funciones y bucles

El anidamiento excesivo hace que el código sea difícil de leer y seguir. Siéntete tentado a refactórelo en funciones más pequeñas.

Ejemplo en JavaScript:

// Función para calcular el área de un círculo
function calcularAreaCirculo(radio) {
    return Math.PI * radio ** 2;
}

// Función principal
function main() {
    try {
        let radio = parseFloat(prompt("Ingrese el radio del círculo:"));
        if (isNaN(radio)) {
            throw new Error("Por favor ingrese un número válido.");
        }
        let area = calcularAreaCirculo(radio);
        console.log(`El área del círculo con radio ${radio} es ${area.toFixed(2)}`);
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Llamada a la función principal
main();

En este código, se evita el anidamiento excesivo de funciones y bucles al utilizar funciones modulares como calcularAreaCirculo() y main(). Además, se utiliza una declaración try…catch para manejar errores de entrada del usuario de manera más legible y evitar el anidamiento de instrucciones condicionales.

3. Comenta adecuadamente tu código

Los comentarios son esenciales para comunicar la intención y las decisiones tomadas al escribir el código a otros desarrolladores (o incluso a ti mismo en el futuro). Sin embargo, evita comentarios redundantes que no aportan información adicional.

Explica el propósito del código o las decisiones tomadas.

Mantén actualizados los comentarios al modificar el código.

Ejemplo en JavaScript:

// Función para calcular el área de un círculo
function calcularAreaCirculo(radio) {
    return Math.PI * radio ** 2; // Fórmula para calcular el área del círculo
}

// Función principal
function main() {
    try {
        // Solicitar al usuario que ingrese el radio del círculo y convertirlo a un número
        let radio = parseFloat(prompt("Ingrese el radio del círculo:"));
        
        // Verificar si el valor ingresado es un número
        if (isNaN(radio)) {
            throw new Error("Por favor ingrese un número válido."); // Lanzar un error si el valor no es un número
        }
        
        // Calcular el área del círculo
        let area = calcularAreaCirculo(radio);
        
        // Mostrar el resultado al usuario con dos decimales de precisión
        console.log(`El área del círculo con radio ${radio} es ${area.toFixed(2)}`);
    } catch (error) {
        console.error("Error:", error.message); // Capturar y mostrar cualquier error que ocurra durante la ejecución
    }
}

// Llamada a la función principal para iniciar el programa
main();

Estos comentarios explican claramente qué hace cada parte del código, lo que facilita su comprensión y mantenimiento.

4. Sigue el principio de responsabilidad única

Cada función o clase debe tener solo una responsabilidad. Así, facilitamos la lectura y mantenimiento del código, además de fomentar la modularidad y reutilización.

Ejemplo en C#:

using System;

// Clase para cálculos relacionados con figuras geométricas
public class CalculadoraGeometrica
{
    // Método estático para calcular el área de un círculo
    public static double CalcularAreaCirculo(double radio)
    {
        return Math.PI * Math.Pow(radio, 2);
    }
}

// Clase para la interacción con el usuario
public class InterfazUsuario
{
    // Método estático para solicitar al usuario el radio del círculo
    public static double SolicitarRadioCirculo()
    {
        double radio;
        while (true)
        {
            Console.Write("Ingrese el radio del círculo: ");
            if (double.TryParse(Console.ReadLine(), out radio))
            {
                return radio;
            }
            else
            {
                Console.WriteLine("Por favor ingrese un número válido.");
            }
        }
    }

    // Método estático para mostrar el resultado al usuario
    public static void MostrarResultado(double radio, double area)
    {
        Console.WriteLine($"El área del círculo con radio {radio} es {area:F2}");
    }
}

// Clase principal
public class Program
{
    public static void Main(string[] args)
    {
        double radio = InterfazUsuario.SolicitarRadioCirculo(); // Solicitar al usuario el radio del círculo
        double area = CalculadoraGeometrica.CalcularAreaCirculo(radio); // Calcular el área del círculo
        InterfazUsuario.MostrarResultado(radio, area); // Mostrar el resultado al usuario
    }
}

En este código, la clase CalculadoraGeometrica tiene la responsabilidad de realizar cálculos relacionados con figuras geométricas, mientras que la clase InterfazUsuario se encarga de interactuar con el usuario para solicitar datos y mostrar resultados. Cada método en estas clases tiene una única responsabilidad, lo que facilita la lectura, mantenimiento y reutilización del código.

5. Mantén tus funciones y clases pequeñas

Trata de mantener tus funciones y clases pequeñas y enfocadas. Esto facilita la comprensión del código y permite la reutilización en otros contextos.

Ejemplo en Ruby:

# Módulo para cálculos relacionados con figuras geométricas
module CalculadoraGeometrica
  # Método para calcular el área de un círculo
  def self.calcular_area_circulo(radio)
    Math::PI * radio**2
  end
end

# Clase para la interacción con el usuario
class InterfazUsuario
  # Método para solicitar al usuario el radio del círculo
  def self.solicitar_radio_circulo
    print "Ingrese el radio del círculo: "
    gets.chomp.to_f
  end

  # Método para mostrar el resultado al usuario
  def self.mostrar_resultado(radio, area)
    puts "El área del círculo con radio #{radio} es #{'%.2f' % area}"
  end
end

# Clase principal
class Programa
  def self.main
    radio = InterfazUsuario.solicitar_radio_circulo # Solicitar al usuario el radio del círculo
    area = CalculadoraGeometrica.calcular_area_circulo(radio) # Calcular el área del círculo
    InterfazUsuario.mostrar_resultado(radio, area) # Mostrar el resultado al usuario
  end
end

# Llamada al método principal
Programa.main

En este código en Ruby, se siguen los principios de mantener las funciones y clases pequeñas. El módulo CalculadoraGeometrica contiene un método para calcular el área de un círculo. La clase InterfazUsuario se encarga de interactuar con el usuario para solicitar datos y mostrar resultados. La clase Programa tiene un único método main que coordina la ejecución del programa. Cada método tiene una única responsabilidad, lo que facilita la comprensión y el mantenimiento del código.

Escribir código limpio, legible y mantenible es fundamental para el éxito de cualquier proyecto de software. Al seguir estas pautas y practicar la escritura de buen código, tanto tú como tu equipo de desarrollo se beneficiarán enormemente al abordar nuevas funcionalidades y corregir errores.

¿Tienes dudas o preguntas sobre cómo escribir código limpio, legible y mantenible? ¡Anímate a compartirlas en la sección de comentarios y permitamos que nuestra comunidad de programadores te ayude a encontrar respuestas!