¿Qué hace Inglés Sencillo?
Di lo principal con tan pocas palabras comunes como sea necesario, y para. El lector abre el código para los detalles.
Sé conciso
- Lidera con el punto: qué hace la cosa y por qué cuando no es obvio.
- Deja fuera lo que el código o el diff ya muestran: los archivos tocados, el orden de los pasos, los casos límite que maneja el código.
- Usa la frase compacta del oficio: "eliminar iconos no usados", no "eliminar los iconos que nada usa".
- Di un hecho una vez.
- Corta palabras, no hechos. Mantén cada paso que el lector necesita para ver el problema y establece la consecuencia: "esa fecha puede diferir del día en que CI hace el lanzamiento", no "el encabezado se escribe antes del día del lanzamiento".
Mantén la claridad
Conciso no es críptico.
- Escribe una idea por oración, con sujeto y verbo. Nada de punto y coma, acertijos o lemas como "sin lanzamiento, sin tipo".
- Pon el sujeto primero y nombra quién actúa: "C++ calcula X", no "X es calculado en C++".
- Usa tiempos simples y el presente para lo que sigue siendo cierto: "QML nunca reevalúa sus enlaces", no "nunca reevaluado".
- Escribe una condición como
Si X, Y. - Repite el sustantivo en lugar de "él", "ella" o "ellos" cuando el sustantivo está varias cláusulas atrás o cuando más de un sustantivo podría encajar.
- Mantén cortas las cláusulas con "que" y "cuyo". Si la cláusula tiene un sujeto largo propio, escribe una oración separada: "Los paquetes Qt de Debian y Ubuntu no lo tienen", no ", que los paquetes Qt de Debian y Ubuntu omiten".
- Di una negación claramente: "ignora valores fuera del rango", no "no tomes ningún valor más allá del rango". No niegues a través del objeto: "la edición no emitió updated()", no "la edición no emitió ningún updated()". Escribe "ni" solo después de "ni".
Suena nativo
El texto debe leerse como algo que escribió un desarrollador angloparlante. Si una frase suena a traducción, reescríbela, aunque la reescritura sea una palabra más larga.
- Usa sustantivos compuestos, no cadenas de "de": "configuración de la aplicación", "el diálogo de archivo CSV", "paquetes Qt de Debian y Ubuntu". Usa un posesivo solo cuando ningún compuesto funciona, como "la densidad de la hoja", y nunca dos seguidos. Permite como máximo un "de" por frase.
- Usa el verbo habitual del oficio: "mostrar", "reportar", "arreglar", "soportar", "manejar", "verificar". No hagas que el código sea una persona que dice, responde o lleva. Mantén "propio" para propiedad en el sentido de C++.
- Usa una palabra por concepto: elige "verificar" o "comprobar", "configuración" u "opciones", y mantén eso.
- No repitas el artículo en una lista: "el marco y botón de eliminar".
- Escribe "debe" para un requisito y "puede" para una posibilidad. Evita "debería", "podría" y "quizás".
- Escribe "por ejemplo", no "p. ej.". Usa ortografía americana.
- Elimina estas palabras: "apalancar" y "utilizar" (escribe "usar"), "con el fin de" (escribe "para"), "previo a" (escribe "antes de"), "asegurar", "simplemente", "solo", "fácilmente", "sin problemas", "robusto", "poderoso", "integral", "funcionalidad", "vale la pena notar que", "con este cambio", "está diseñado para", "te permite" (nombra la cosa y su verbo), "bajo el capó", "listo para usar".
Antes y después, de temas de commit reales:
| Antes | Después |
|---|---|
| mantener la configuración de la aplicación fuera de los documentos | no guardar la configuración de la aplicación en documentos |
| Gráfico: decirle al lector cuando una exportación falla | Gráfico: reportar errores de exportación |
| agregar CardButton, el botón de icono de la fila superior de un objeto | agregar CardButton, el botón de icono en la fila superior de un objeto |
| Sampler: no tomar ningún valor de un objeto discreto más allá de su rango | Sampler: ignorar valores de objetos discretos fuera del rango |
| detener un lanzamiento completo cuyas notas llevan otro día | verificar la fecha en las notas de lanzamiento antes de un lanzamiento completo |
| compilar en Ubuntu 26.04, con sus paquetes de Qt | compilar en Ubuntu 26.04, con sus paquetes Qt |
Por tipo de texto
Mensaje de commit
- Escribe el tema como un imperativo corto que tenga sentido sin el diff: "limitar los valores del documento a los límites del panel de configuración", no "mantener los números de un documento dentro del rango del panel".
- Un commit hace una sola cosa. Si el cuerpo necesita un segundo tema, divide el commit.
- Empieza el cuerpo con lo que el código hace ahora, luego un breve por qué.
- Marca un hecho más allá del tema con "también": "Ambas lecturas también omiten claves desconocidas, porque versiones más nuevas pueden agregar algunas."
- Omite el contexto que el lector ya conoce. No vuelvas a contar el diff ni defiendas el cambio.
Comentario de código
- No escribas ninguno por defecto. Escribe uno por una razón que el código no muestra, una invariante oculta o una solución alternativa.
- Di qué hace el código, qué se sigue de ello y por qué, una oración corta cada uno. Omite una parte que el código ya muestra.
- Nombra la API y no uses metáforas. El imperativo está bien: "omitir escrituras idénticas: aún actualizan el mtime".
- Escribe el comentario que le darías a un colega que pregunta "¿por qué está esto aquí?". Nombra el efecto concreto, como "xmin permanece a la izquierda", no un resumen como "los límites están donde están".
Ejemplos:
- Antes:
// una lista vertical mantiene su ancho en secreto, por lo que el estilo pinta un controlador extraviado - Después:
// un ListView vertical deja contentWidth en -1, que el estilo renderiza como un controlador colapsado - Antes:
# el glib y libsystemd del runner necesitan su nueva glibc, por lo que el AppImage usa el glib y libdbus del host. linuxdeploy aún copia las bibliotecas que solo ellos necesitan, así que la lista también las nombra - Después:
# no empaquetar glib, libdbus ni sus dependencias. El AppImage carga entonces las versiones del host. Las versiones de Ubuntu 26.04 necesitan glibc 2.43, que las distribuciones antiguas no tienen.
Documentación
- Describe lo que el código hace hoy. Nombra la cosa y para qué sirve, y señala el archivo con los detalles.
- Pon tres o más elementos paralelos en una lista con viñetas.
- Pon los nombres de estilo, módulo e identificador entre acentos graves:
FluentWinUI3. - Marca un hecho sobre software de terceros que pueda cambiar con "actualmente" o la versión: "Los paquetes Qt de Debian y Ubuntu actualmente no lo tienen."
Mensaje de error: qué sucedió, la causa si se conoce y qué hacer. Sin disculpas.
Tooltip: qué establece el widget.
Instrucciones para un agente: una regla por oración, la condición primero.
Deja tranquilo
Código, identificadores, comandos, rutas, mensajes entre comillas, nombres de productos y nombres de botones, pestañas, campos y entradas de menú.
Antes de entregar
Lee el texto una vez como su lector. Elimina cada oración que no ayude a ese lector. Verifica que cada oración restante se lea bien la primera vez y suene a inglés habitual.
Si explicaste lo mismo en el chat, compara los dos. Si la versión del chat es más clara, úsala.