Escribir comentarios y un README en inglés

Hasta ahora has leído inglés técnico. Escribirlo es el paso siguiente, y es más fácil de lo que parece, porque los comentarios y los README usan frases cortas, directas y muy repetitivas. En esta lección aprenderás a comentar tu código, a documentar funciones y a escribir un README que otros entiendan, con plantillas que puedes adaptar.

Comentarios en el código

Un comment (/cóment/) es texto que el programa ignora y que escribes para humanos. Sirven para explicar el por qué de algo, no el qué. Si el código ya dice qué hace, el comentario sobra.

Lenguaje	Comentario de una línea	Comentario de varias líneas
JavaScript, Java, PHP, TypeScript	// comment	/* comment */
Python	# comment	Varias líneas con #, o un texto entre """
SQL	-- comment	/* comment */
HTML	no existe	<!-- comment -->
CSS	no existe	/* comment */

Mira la diferencia entre un comentario inútil y uno útil:

// Bad: repeats the code
// Add 1 to i
i = i + 1;

// Good: explains why
// The API counts pages from 1, not from 0
const page = index + 1;

El primero repite lo que ya se lee; el segundo explica una razón que el código no deja ver.

Frases modelo para comentarios

Los comentarios usan el tiempo presente y suelen empezar por un verbo o por una descripción corta. Estas son fórmulas que puedes copiar:

Para decir…	Escribe…
Por qué	// Needed because the API returns a string
Aviso	// Do not change this value without updating the tests
Condición	// Skip empty rows
Solución provisoria	// Temporary workaround until the bug is fixed
Cómo funciona	// Sort by date, newest first
Referencia	// See https://example.com/docs for details
Unidades	// Time in milliseconds
Suposición	// Assumes the list is already sorted
Restricción	// Must be called after init()

Verbos útiles: skip (/skip/, saltar), ignore (/ignór/, ignorar), assume (/asiúm/, suponer), handle (/jándol/, gestionar), check (/chek/, comprobar), ensure (/enshúr/, asegurar), avoid (/avoid/, evitar), retry (/rítrai/, reintentar).

Marcas especiales: TODO, FIXME, HACK, NOTE

Los programadores usan etiquetas en mayúsculas para marcar cosas pendientes. Los editores las resaltan y se pueden buscar con Ctrl + F.

Etiqueta	Pronunciación	Significado	Ejemplo
TODO	/tu-du/	por hacer	// TODO: validate the email format
FIXME	/fiks mi/	arreglar: algo está roto	// FIXME: crashes when the list is empty
HACK	/jak/	apaño, solución sucia	// HACK: delay needed on slow devices
NOTE	/nout/	nota	// NOTE: this runs only once
XXX	/ex ex ex/	atención, peligro	// XXX: this is fragile
DEPRECATED	/déprikeitid/	obsoleto	// DEPRECATED: use newFunction() instead

Ejemplo real:

function applyDiscount(price, discount) {
  // TODO: support discounts above 100 %
  // Discount cannot be negative
  if (discount < 0) throw new Error("Discount must be positive");
  return price - (price * discount) / 100;
}

console.log(applyDiscount(80, 25)); // 60

Cuidado: no dejes TODO olvidados durante años. Si algo queda pendiente, apúntalo también en un gestor de tareas o como issue del repositorio.

Documentar funciones: JSDoc y docstrings

Además de los comentarios sueltos, hay formatos estándar para explicar qué hace una función. Los editores los usan para mostrarte ayuda al escribir.

JSDoc en JavaScript

/**
 * Calculates the final price after applying a discount.
 * @param {number} price - The original price.
 * @param {number} discount - The discount as a percentage (0-100).
 * @returns {number} The price after the discount.
 */
function applyDiscount(price, discount) {
  return price - (price * discount) / 100;
}

Etiqueta	Pronunciación	Significado
@param	/param/	describe un parámetro
@returns	/ritérns/	qué devuelve
@throws	/zrous/	qué error puede lanzar
@example	/egsámpol/	un ejemplo de uso
@deprecated	/déprikeitid/	marca como obsoleto
@see	/si/	referencia relacionada

La primera frase describe la función en tercera persona del presente: “Calculates…”, “Returns…”, “Checks…”. No es “Calculate” ni “I calculate”.

Docstrings en Python

En Python, la descripción va entre triples comillas justo después de la línea def:

def apply_discount(price, discount):
    """Return the price after applying a percentage discount.

    Args:
        price: The original price.
        discount: The discount as a percentage (0-100).
    """
    return price - price * discount / 100

print(apply_discount(80, 25))  # 60.0

Un docstring (/dócstring/, de documentation string) se puede leer con help(apply_discount). Aquí la primera frase empieza con un verbo en imperativo: “Return the price…”. Es la convención de Python (PEP 257). Elige un estilo (tercera persona o imperativo) y mantenlo en todo el proyecto.

El README

El archivo README.md es lo primero que ve alguien al abrir tu proyecto en GitHub. README viene de “read me” (/rid mi/, “léeme”). La extensión .md indica Markdown, un formato de texto sencillo. Debe responder en 30 segundos: qué es esto, cómo lo instalo, cómo se usa.

Secciones habituales

Sección	Pronunciación	Para qué sirve
Title + descripción	/táitl/	Qué es el proyecto, en una frase
Features	/fíchers/	Lista de funcionalidades
Demo / Screenshots	/démo/, /scríenshots/	Cómo se ve
Installation	/instaléishon/	Cómo instalarlo
Usage	/iúsidy/	Cómo se usa, con ejemplos
Configuration	/konfiguiuréishon/	Opciones y variables de entorno
Contributing	/kontríbiuting/	Cómo colaborar
License	/láisens/	Con qué licencia se publica
Credits / Acknowledgments	/críditos/	Agradecimientos
Roadmap	/róudmap/	Planes futuros
Contact	/cóntact/	Cómo contactar

Una plantilla completa

Este es un README original para una app inventada de rutas de senderismo. Está escrito con frases muy sencillas:

# Trail Notes

A small web app to save and share your hiking routes.

## Features

- Save routes with distance, time and difficulty.
- Add photos and notes to each route.
- Search routes by name or location.

## Installation

1. Clone the repository:
   `git clone https://github.com/example/trail-notes.git`
2. Go to the project folder: `cd trail-notes`
3. Install the dependencies: `npm install`
4. Start the app: `npm start`

The app will be available at `http://localhost:3000`.

## Usage

Open the app in your browser and click **New route**.
Fill in the form and press **Save**.

## Requirements

- Node.js 20 or higher

## Contributing

Pull requests are welcome. For major changes, please open an issue
first to discuss what you would like to change.

## License

MIT

Y su traducción de las partes importantes:

Frase	Traducción
A small web app to save and share...	Una pequeña aplicación web para guardar y compartir…
Clone the repository	Clona el repositorio
Install the dependencies	Instala las dependencias
The app will be available at...	La aplicación estará disponible en…
Pull requests are welcome	Se aceptan pull requests
Please open an issue first	Por favor, abre antes un issue
Node.js 20 or higher	Node.js 20 o superior

Imperativo: el tiempo del README

Las instrucciones se escriben en imperativo (la forma del verbo sin sujeto): Install, Run, Open, Press, Click, Create, Add, Set. No se escribe “You should install” salvo para recomendaciones.

Verbo	Pronunciación	Significado	Ejemplo
Clone	/clóun/	clonar	Clone the repository
Install	/instól/	instalar	Install the dependencies
Run	/ran/	ejecutar	Run the tests
Open	/óupen/	abrir	Open the browser
Create	/criéit/	crear	Create a .env file
Set	/set/	establecer	Set the API key
Press / Click	/pres/, /clik/	pulsar / hacer clic	Click Save
Make sure	/meik shur/	asegurarse de	Make sure Node is installed

Otras frases habituales: “Replace X with your own value” (sustituye X por tu valor), “This step is optional” (este paso es opcional), “If you see an error…” (si ves un error…), “Note that…” (ten en cuenta que…), “For more details, see…” (para más detalles, mira…).

Y la sintaxis de Markdown que necesitas:

Quieres	Escribes
Título	# Title
Subtítulo	## Subtitle
Negrita	**bold**
Código en línea	`code`
Bloque de código	tres comillas inversas (backticks) con el lenguaje
Lista	- item
Lista numerada	1. step
Enlace	[text](https://url)

Otras piezas que escribirás

• Un issue (/íshiu/): una incidencia o petición en GitHub. Un buen título es corto y concreto: Login button does not respond on mobile.
• Una descripción de pull request: qué cambias y por qué. Se ve con más detalle en Git y commits.
• Mensajes de commit: frases muy cortas en imperativo.
• Cambios en el CHANGELOG: listas de Added (añadido), Changed (cambiado), Fixed (arreglado) y Removed (eliminado).

Errores frecuentes

• Comentar el qué en vez del por qué. // add 1 no sirve; // the API counts from 1 sí.
• Mezclar español e inglés en el mismo archivo. Si tu README es en inglés, todo en inglés. Si es en español, todo en español.
• Escribir frases largas y complicadas. En inglés técnico, mejor tres frases cortas que una larga.
• Usar “you” por todas partes. En instrucciones usa imperativo: “Run the tests”, no “You have to run the tests”.
• Dejar un README vacío o con el texto por defecto. Un README sin instalación ni uso es como una caja cerrada.
• Olvidar los bloques de código. Los comandos van en bloques con backticks para copiarlos sin errores.
• Dejar TODO sin dueño ni fecha. Anótalos en un issue.

Resumen

Elemento	Cómo se escribe
Comentario	Explica el por qué, en presente y breve
TODO / FIXME	Pendiente / roto: // TODO: ...
JSDoc	/** ... */ con @param, @returns
Docstring	"""...""" bajo def
README	Title, Features, Installation, Usage, Contributing, License
Instrucciones	Imperativo: Clone, Install, Run, Open
Formato	Markdown (.md)

Terminamos este bloque con un vocabulario que usarás cada día si colaboras en proyectos: Git y commits.