Escribir comentarios en código

¿Por qué escribir comentarios en inglés?

Cuando trabajas en proyectos con desarrolladores de diferentes países, los comentarios en inglés aseguran que todos comprendan tu código. Además, la mayoría de la documentación técnica, librerías y recursos de aprendizaje están en inglés. Dominar la escritura de comentarios en inglés es una habilidad profesional indispensable.

Tipos de comentarios en programación

1. Comentarios de una sola línea (Single-line comments)

Se usan para explicaciones breves y precisas. Son ideales para документировать decisiones inmediatas.

// Calculate user age from birthdate
const age = calculateAge(user.birthDate);

// Validate input to prevent errors
if (input !== null) { ... }

# Python example
# Fetch data from API endpoint
response = requests.get(url)

2. Comentarios de bloque (Block comments)

Abarcan múltiples líneas y se utilizan para explicaciones más detalladas o secciones completas de código.

/*
 * This function handles user authentication
 * Input: username and password
 * Output: authentication token or null
 * Throws: AuthException if credentials are invalid
 */
function authenticate(username, password) {
    // implementation
}

/*
  Multiline comment in Python
  Used for longer explanations
  across several lines
*/

3. Documentación con JSDoc/Docstring

Permiten generar documentación automática y son estándar en la industria.

/**
 * Calculates the total price including tax and discounts
 * @param {number} basePrice - The original price
 * @param {number} taxRate - Tax percentage (e.g., 0.21 for 21%)
 * @param {number} discount - Discount amount to subtract
 * @returns {number} Final price after taxes and discounts
 */
function calculateTotalPrice(basePrice, taxRate, discount) {
    return (basePrice + (basePrice * taxRate)) - discount;
}

"""
Retrieves user information from the database.

Args:
    user_id (int): The unique identifier of the user
    
Returns:
    dict: A dictionary containing user data
    
Raises:
    UserNotFoundError: If user_id does not exist in database
"""
def get_user(user_id):
    pass

Vocabulario esencial para comentarios

Buenas prácticas para comentarios efectivos

1. Comenta el POR QUÉ, no el QUÉ: El código ya muestra qué hace. Tu comentario debe explicar la razón detrás de la decisión.
2. Usa frases cortas y claras: «// Check if user is logged in» es mejor que «// This comment is for checking the authentication status of the user before proceeding».
3. Mantén los comentarios actualizados: Un comentario desactualizado es peor que no tener ninguno, ya que confunde a otros desarrolladores.
4. Elimina comentarios obvios: No escribas «// Increment i by 1» cuando el código ya dice «i++».
5. Utiliza mayúsculas para palabras clave: TODO, FIXME, HACK, NOTE son estándar en la industria.

Estructuras gramaticales útiles

Frases en presente simple

Los comentarios usan presente simple porque describen lo que el código hace de forma general y atemporal.

// Returns the user object
// Calculates total based on quantity
// Handles the error gracefully
// Initializes the connection

Frases en imperativo

Especialmente en TODOs y documentación de funciones, el imperativo indica acciones necesarias.

// TODO: Add error handling
// FIXME: Memory leak in loop
// HACK: Remove this after v2.0 release
// OPTIMIZE: Use caching for better performance

Frases con tercera persona

En la documentación de funciones (JSDoc), se usa third person singular.

/**
 * Calculates the shipping cost
 * Handles user authentication
 * Returns the formatted date
 */

Comentarios internacionales vs. comentarios locales

En equipos internacionales, es fundamental establecer un estándar. Aquí hay una comparación:

Señales de seguimiento (Trackers)

Son palabras clave que indican el estado o tipo de comentario. Son universales en programación:

// TODO: Implement password reset functionality
// FIXME: This crashes with special characters
// HACK: Workaround for browser compatibility issue
// NOTE: This algorithm is O(n²), consider optimization
// BUG: Issue #1234 - Race condition in async handler
// DEPRECATED: Use UserService.getById() instead

// Single line comment
/* Block comment */
/** JSDoc documentation */

// Ejemplo completo:
/**
 * Adds two numbers together
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 */
function add(a, b) {
    return a + b;
}

// TODO: Add input validation
// NOTE: Returns NaN if inputs are not numbers

# Single line comment
""" Docstring for function/class """

# Ejemplo completo:
def multiply(a, b):
    """
    Multiplies two numbers
    
    Args:
        a (int/float): First factor
        b (int/float): Second factor
        
    Returns:
        int/float: Product of a and b
    """
    return a * b

# TODO: Add support for complex numbers
# HACK: Works only with positive integers

// Single line comment
/* Block comment */
/** JavaDoc documentation */

// Ejemplo completo:
/**
 * Calculates the area of a circle
 * @param radius The radius of the circle
 * @return The area as a double
 * @throws IllegalArgumentException if radius is negative
 */
public double calculateArea(double radius) {
    return Math.PI * radius * radius;
}

// FIXME: Handle zero radius
// TODO: Add overload for diameter parameter

Pattern común: Comentarios de sección

En archivos grandes, usa comentarios para separar secciones lógicas:

// ============================================
// USER AUTHENTICATION MODULE
// ============================================

// --- Login Functions ---

// --- Password Recovery ---

// --- Session Management ---

// ============================================
// END OF AUTHENTICATION MODULE
// ============================================

// También se usa:
// **********************
// * Helper Functions    *
// **********************

# En Python también puedes usar:
# ==============================
# SECTION: Database Operations
# ==============================

Errores gramaticales comunes a evitar

«Write comments to help your future self and other developers understand your code. If you can't explain it simply, you don't understand it well enough yet.» — Principio de documentación técnica

Resumen y próximos pasos

Ahora que conoces los fundamentos de los comentarios en inglés para código, practica incorporando estas técnicas en tu código diario:

1. Revisa tu último proyecto y añade comentarios en inglés donde sea necesario
2. Practica escribir JSDoc/Docstrings para tus funciones
3. Familiarízate con los trackers: TODO, FIXME, HACK, NOTE
4. Lee código de proyectos open source para ver cómo documentan otros desarrolladores
5. Configura tu IDE para reconocer y resaltar estos comentarios

En la próxima lección de este módulo, exploraremos cómo escribir mensajes de commit descriptivos en inglés, otra habilidad esencial para cualquier desarrollador que trabaje en equipos profesionales o proyectos colaborativos.