Vocabulario de inglés técnico para developers

Inglés Técnico para Programadores: Mensajes de Error, Docs de APIs, Comentarios y Jerga

Una guía práctica de vocabulario para developers hispanohablantes que leen mensajes de error, documentación de APIs y comentarios de código en inglés todos los días.

Puntos clave

Los mensajes de error tienen tres partes: tipo, descripción y ubicación. Copia solo la descripción cuando busques.
El vocabulario de documentación de APIs (deprecated, nullable, throws, idempotent) es el mismo en todos los lenguajes y frameworks.
TODO significa una tarea. FIXME significa un bug conocido. HACK significa feo-pero-funciona. NOTE significa contexto importante.
Las convenciones de nombres en inglés (camelCase, snake_case, PascalCase) son obligatorias en proyectos open source.
La jerga técnica como 'yak shaving', 'footgun' y 'bikeshedding' está en todas partes en la comunicación de developers.

El inglés que lees todos los días como developer

The English you read every day as a developer

No estás leyendo una novela. Estás leyendo un stack trace, un README de GitHub, un comentario JSDoc o una referencia de la API de Stripe. Este tipo de inglés tiene sus propios patrones, su propio vocabulario y sus propias convenciones.

Esta guía cubre el inglés técnico que vive dentro de tus herramientas: cómo leer y buscar mensajes de error, qué significan palabras como `deprecated`, `nullable` y `throws` en la documentación de APIs, qué señalan `TODO`, `FIXME` y `HACK` en los comentarios de código, por qué las convenciones de nombres en inglés importan para el trabajo en open source, y un glosario de 16 términos de jerga que encontrarás en cualquier equipo que trabaje en inglés.

Esta no es una guía general de inglés. Complementa la guía de flujo de trabajo en /ingles-para-programadores, que cubre standups, reuniones, pull requests y entrevistas. Esta guía se enfoca en el vocabulario dentro del código.

Qué hay en esta guía

1. Mensajes de error: cómo leerlos y buscarlos
2. Vocabulario de documentación de APIs: deprecated, returns, throws, nullable
3. Convenciones de comentarios: TODO, FIXME, HACK, NOTE
4. Convenciones de nombres en inglés: por qué importan en open source
5. Glosario de jerga técnica: 16 términos que todo developer necesita

Mensajes de Error: Cómo Leerlos y Buscarlos

Error messages: how to read and search them

Los mensajes de error siguen un patrón. Una vez que reconoces el patrón, puedes extraer la información que necesitas en segundos, aunque no entiendas cada palabra.

Un mensaje de error típico tiene tres partes: el tipo de error, una descripción legible y una ubicación (archivo, número de línea, columna). Aquí hay un ejemplo de Node.js:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserList (/app/components/UserList.jsx:12:22)
    at renderWithHooks (/app/node_modules/react-dom/cjs/react-dom.development.js:14985:18)

TypeError

El tipo de error. En JavaScript: TypeError, ReferenceError, SyntaxError, RangeError. Cada tipo te dice la categoría del problema.

Cannot read properties of undefined (reading 'map')

La descripción legible. Esto es lo que pegas en Google. Siempre copia la descripción, no el stack trace completo.

at UserList (/app/components/UserList.jsx:12:22)

La ubicación. Ruta del archivo, línea 12, columna 22. Aquí está tu código.

Cuando buscas un error, pega solo el mensaje, no las rutas de archivos. Las rutas son específicas de tu proyecto y no devolverán resultados. El mensaje es lo que otros developers han visto antes.

Traceback (most recent call last):
  File "main.py", line 8, in <module>
    result = divide(10, 0)
  File "main.py", line 4, in divide
    return a / b
ZeroDivisionError: division by zero

Python muestra un traceback, que es el call stack en orden inverso. Lee de abajo hacia arriba: la última línea es el error, y las líneas anteriores te muestran cómo llegó el código hasta allí.

Consejos para buscar mensajes de error

1.Elimina las partes específicas de tu proyecto (nombres de archivos, nombres de variables).
2.Agrega el lenguaje o framework: "Python ZeroDivisionError", "React TypeError cannot read properties".
3.Agrega la versión de la librería si el error está en una dependencia.
4.Si Google no devuelve nada, prueba Stack Overflow directamente con el mensaje de error exacto entre comillas.

Vocabulario de Documentación de APIs

API documentation vocabulary

La documentación de APIs sigue convenciones. Una vez que conoces el vocabulario, puedes leer cualquier referencia de API, ya sea Stripe, GitHub, AWS o una librería que nunca hayas usado.

Término	Qué significa	Ejemplo de documentación
deprecated	Esta funcionalidad todavía funciona pero se eliminará en una versión futura. No la uses en código nuevo.	@deprecated Use `getUserById` instead. This method will be removed in v4.0.
returns	Lo que devuelve la función. Siempre seguido del tipo y una descripción.	@returns {Promise<User>} The user object, or null if not found.
throws	Qué error lanza la función si algo sale mal. Importante para el manejo de errores.	@throws {AuthError} If the token is expired or invalid.
nullable	El valor puede ser null. Debes verificar si es null antes de usarlo.	user.avatarUrl: string \| null: nullable. Check before rendering.
optional	El parámetro no tiene que ser proporcionado. Tiene un valor por defecto o puede ser undefined.	function createUser(name: string, role?: string): role is optional.
idempotent	Llamar a este endpoint varias veces con el mismo input tiene el mismo efecto que llamarlo una vez. Seguro para reintentar.	DELETE /users/:id is idempotent: deleting a user twice leaves the user deleted.
paginated	La respuesta devuelve un subconjunto de resultados. Usa cursor o parámetros de página para obtener el resto.	GET /orders returns 20 results by default. Use ?page=2 to get the next 20.
rate limited	La API limita cuántas peticiones puedes hacer en una ventana de tiempo. Excederla devuelve un error 429.	This endpoint is rate limited to 100 requests per minute per API key.

JSDoc es el formato más común para documentación de APIs en JavaScript/TypeScript. También verás OpenAPI (para APIs REST), rustdoc (Rust) y godoc (Go). El vocabulario anterior aplica a todos.

Convenciones de Comentarios: TODO, FIXME, HACK, NOTE

Code comment conventions: TODO, FIXME, HACK, NOTE

Estas etiquetas no son sintaxis oficial, son convenciones que usan todos los developers en todos los equipos. Tu editor las resalta. La búsqueda de GitHub puede encontrarlas. Comunican intención y urgencia.

TODOurgencia: baja a media

Algo que hay que hacer pero que no está hecho todavía. No es un bug. A menudo se deja durante un sprint cuando sabes que vas a volver.

// TODO: add pagination once the dataset grows beyond 1000 records

FIXMEurgencia: media a alta

Hay un bug conocido aquí. El código funciona por ahora pero fallará bajo ciertas condiciones. Mayor urgencia que TODO.

// FIXME: this breaks if the user has no address: null check needed

HACKurgencia: variable

Funciona pero la implementación es fea, frágil o depende de algo que no debería. Un marcador de deuda técnica.

// HACK: the API returns dates as strings in 'DD/MM/YYYY' format: parse manually until we migrate to ISO 8601

NOTEurgencia: informativo

Contexto importante para quien lea este código. No es un bug, no es una tarea, solo algo que necesitas saber.

// NOTE: this endpoint is called by the mobile app: do not change the response shape without coordinating with the mobile team

Cuando dejas un TODO o FIXME, agrega tu nombre y la fecha si tu equipo no usa un tracker de tickets: `// TODO(alex, 2024-03): move this to a background job`. Esto ayuda a los developers futuros a entender si el comentario sigue siendo relevante.

Convenciones de Nombres en Inglés

Naming conventions in English

En open source y equipos internacionales, las convenciones de nombres en inglés no son opcionales. Una función llamada `obtenerUsuario` en un proyecto Python al que contribuye todo el mundo no va a ser aceptada. Esto es lo que necesitas saber.

Convención	Se usa en	Ejemplos	Nota
camelCase	JavaScript/TypeScript: variables, funciones, métodos	getUserById, isAuthenticated, maxRetries	Empieza con minúscula. Cada nueva palabra empieza con mayúscula.
PascalCase	JavaScript/TypeScript: clases, componentes React, tipos, interfaces	UserService, AuthProvider, HttpError	Empieza con mayúscula. Cada nueva palabra empieza con mayúscula.
snake_case	Python: variables, funciones, nombres de módulos. También: columnas SQL, variables de entorno.	get_user_by_id, is_authenticated, max_retries	Todo en minúsculas. Palabras separadas por guiones bajos.
SCREAMING_SNAKE_CASE	Constantes en la mayoría de lenguajes, variables de entorno	MAX_RETRY_COUNT, DATABASE_URL, API_KEY	Todo en mayúsculas. Palabras separadas por guiones bajos.
kebab-case	URLs, nombres de clases CSS, nombres de archivos (en muchos proyectos)	user-profile, login-button, get-started.tsx	Todo en minúsculas. Palabras separadas por guiones.

Principios de nomenclatura

Nombra las cosas en inglés, incluso en proyectos privados. Te lo agradecerás cuando compartas el código.
Usa palabras completas, no abreviaciones: `getUserById` no `getUsrById`. `response` no `res` (a menos que sea una abreviación bien conocida en el framework).
Las variables y funciones booleanas deben leerse como una pregunta: `isLoggedIn`, `hasPermission`, `canDelete`.
Las funciones que devuelven valores deben empezar con un verbo: `getUser`, `fetchOrders`, `calculateTotal`.
Evita nombres genéricos: `data`, `info`, `thing`, `stuff`. Sé específico: `userProfile`, `orderItems`, `errorMessage`.

Glosario de Jerga Técnica

Technical jargon glossary

Estos son los términos que escucharás en code reviews, discusiones de arquitectura y threads de Slack. No están en los diccionarios de inglés estándar. Los developers hispanohablantes a menudo los encuentran sin contexto.

Término	Español	Oración de ejemplo	Nota
legacy	código heredado / antiguo	We cannot refactor that module: it is legacy code that three other services depend on.	A menudo se usa para referirse a código antiguo que es difícil de cambiar, no necesariamente malo.
edge case	caso borde / caso extremo	What happens if the user has no email address? That is an edge case we need to handle.	Una entrada o condición en el límite de lo que el sistema está diseñado para manejar.
race condition	condición de carrera	If two requests hit this endpoint at the same time, you get a race condition and duplicate records.	Un bug que solo ocurre cuando dos operaciones se ejecutan en paralelo y su orden importa.
footgun	trampa / arma contra uno mismo	Mutable default arguments in Python are a classic footgun.	Una característica de un lenguaje o herramienta que facilita accidentalmente causarse problemas a uno mismo.
idempotent	idempotente	Make sure the migration script is idempotent so we can run it multiple times without side effects.	Una operación que puedes realizar múltiples veces y obtener el mismo resultado que si la hicieras una sola vez.
backfill	rellenar / retroalimentar datos	We need to backfill the `created_at` column for existing users.	Llenar datos históricos faltantes, generalmente en una migración de base de datos o pipeline de análisis.
shim	adaptador / capa de compatibilidad	We added a shim so the old API clients still work after the endpoint change.	Una capa delgada de código que hace que una interfaz sea compatible con otra.
bikeshedding	debatir trivialidades / perder el tiempo en lo irrelevante	We spent an hour bikeshedding over the button color instead of reviewing the architecture.	Dedicar tiempo desproporcionado a decisiones triviales mientras se ignoran las importantes. De la Ley de Trivialidad de Parkinson.
yak shaving	hacer tareas previas interminables para llegar al objetivo real	I started by adding a feature, ended up yak shaving: upgrading Node, fixing the build, updating types.	Una cadena de tareas previas que tienes que completar antes de poder hacer la tarea original.
rubber duck debugging	depurar explicando el problema en voz alta	I explained the bug to a rubber duck and realized the problem myself before asking for help.	La técnica de explicar tu código en voz alta a un objeto inanimado (tradicionalmente un pato de goma) para encontrar el bug.
DRY	No te repitas (Do Not Repeat Yourself)	Extract that logic into a helper function. DRY principle.	Cada pieza de conocimiento debe tener una representación única y sin ambigüedades en el sistema.
YAGNI	No lo vas a necesitar (You Are Not Gonna Need It)	Do not build that abstraction yet. YAGNI: we will add it when we actually need it.	No agregues funcionalidad hasta que sea necesaria. Previene el sobreingeniería.
KISS	Mantenlo simple, estúpido (Keep It Simple, Stupid)	This could be a simple if-else. KISS. Do not over-engineer it.	Prefiere la solución más simple que funcione. La complejidad es una responsabilidad.
tech debt	deuda técnica	We shipped fast but we took on tech debt. We need a sprint to pay it down.	El costo implícito del retrabajo futuro causado por elegir una solución rápida ahora en lugar de un enfoque mejor que tomaría más tiempo.
greenfield	proyecto nuevo / desde cero	This is a greenfield project. We chose the stack ourselves with no legacy constraints.	Un proyecto construido desde cero sin una base de código existente.
brownfield	proyecto con código heredado / existente	It is a brownfield project. Every change has to be backward compatible.	Un proyecto construido sobre código existente, con las restricciones que eso conlleva.

¿Listo para practicar tu inglés en el trabajo?

Lingua-e tiene ejercicios interactivos basados en conversaciones reales de developers: standups, code reviews, retrospectivas y más. Practica hasta que salga solo.

Prueba Lingua-e gratis

Escrito por

Roxana Lafuente

Fundadora de Lingua-e

Roxana Lafuente es ingeniera de software con más de 8 años de experiencia. Al comienzo de su carrera, aunque ya había aprobado el First Certificate in English, se bloqueaba cada vez que tenía que hablar en el standup diario. Era un problema que nadie estaba resolviendo. Después de más de 2.000 standups, descubrió qué es lo que realmente construye la fluidez: practicar situaciones que se parecen a tu trabajo real. Creó Lingua-e para que otros developers no tuvieran que tomar el camino largo para sentirse seguros trabajando en un entorno de desarrollo internacional.