El mensaje principal debe ser breve, fáctico y evitar referencias a detalles de implementación, como nombres de funciones específicos. “Breve” significa que “debería caber en una sola línea bajo condiciones normales”. Utiliza un mensaje de detalle si es necesario para mantener breve el mensaje principal, o si sientes la necesidad de mencionar detalles de implementación, como la llamada al sistema particular que falló. Tanto el mensaje principal como el de detalle deben ser fácticos. Utiliza un mensaje de sugerencia (hint) para sugerir qué hacer para solucionar el problema, especialmente si la sugerencia no siempre es aplicable.

Por ejemplo, en lugar de:

IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(además de una larga adición que es básicamente una sugerencia)

escribe:

Principal:  could not create shared memory segment: %m
Detalle:    Failed syscall was shmget(key=%d, size=%u, 0%o).
Sugerencia: The addendum, written as a complete sentence.

Justificación: mantener el mensaje principal breve ayuda a que vaya al grano y permite a los clientes diseñar el espacio de la pantalla asumiendo que una línea es suficiente para los mensajes de error. Los mensajes de detalle y sugerencia pueden relegarse a un modo detallado (verbose), o tal vez a una ventana emergente de detalles de error. Además, los detalles y sugerencias normalmente se suprimirían del registro del servidor para ahorrar espacio. Es mejor evitar la referencia a detalles de implementación, ya que no se espera que los usuarios conozcan dichos detalles.

No incluyas suposiciones específicas sobre el formato en los textos de los mensajes. Espera que los clientes y el registro del servidor ajusten las líneas para adaptarse a sus propias necesidades. En los mensajes largos, se pueden utilizar caracteres de salto de línea (\n) para indicar los saltos de párrafo sugeridos. No termines un mensaje con un salto de línea. No utilices tabulaciones u otros caracteres de formato. (En las pantallas de contexto de error, los saltos de línea se añaden automáticamente para separar los niveles de contexto, como las llamadas a funciones).

Justificación: Los mensajes no se muestran necesariamente en pantallas de tipo terminal. En las pantallas de interfaz gráfica de usuario (GUI) o en los navegadores, estas instrucciones de formato se ignoran en el mejor de los casos.

El texto en inglés debe utilizar comillas dobles cuando sea apropiado entrecomillar. El texto en otros idiomas debe utilizar de forma coherente un tipo de comillas que sea acorde con las costumbres de publicación y la salida de ordenador de otros programas.

Justificación: La elección de comillas dobles sobre comillas simples es algo arbitraria, pero tiende a ser el uso preferido. Algunos han sugerido elegir el tipo de comillas según el tipo de objeto de acuerdo con las convenciones SQL (es decir, cadenas entre comillas simples, identificadores entre comillas dobles). Pero este es un problema técnico interno del lenguaje con el que muchos usuarios ni siquiera están familiarizados, no se adaptará a otros tipos de términos entrecomillados, no se traduce a otros idiomas y, además, no tiene mucho sentido.

Utiliza siempre comillas para delimitar nombres de archivos, identificadores proporcionados por el usuario, nombres de variables de configuración y otras variables que puedan contener palabras. No las utilices para marcar variables que no vayan a contener palabras (por ejemplo, nombres de operadores).

Hay funciones en el backend que encerrarán entre comillas dobles su propia salida según sea necesario (por ejemplo, format_type_be()). No pongas comillas adicionales alrededor de la salida de dichas funciones.

Justificación: Los objetos pueden tener nombres que crean ambigüedad cuando se incrustan en un mensaje. Sé coherente al denotar dónde comienza y termina un nombre insertado. Pero no sobrecargues los mensajes con comillas innecesarias o duplicadas.

Las reglas son diferentes para los mensajes de error principales y para los mensajes de detalle/sugerencia:

Mensajes de error principales: No comiences con mayúscula la primera letra. No termines un mensaje con un punto. Ni se te ocurra terminar un mensaje con un signo de exclamación.

Mensajes de detalle y sugerencia: Utiliza oraciones completas y termina cada una con un punto. Comienza con mayúscula la primera palabra de las oraciones. Pon dos espacios después del punto si sigue otra oración (para el texto en inglés; podría ser inadecuado en otros idiomas).

Cadenas de contexto de error: No comiences con mayúscula la primera letra y no termines la cadena con un punto. Las cadenas de contexto normalmente no deben ser oraciones completas.

Justificación: Evitar la puntuación facilita a las aplicaciones cliente incrustar el mensaje en una variedad de contextos gramaticales. A menudo, los mensajes principales no son oraciones gramaticalmente completas de todos modos. (Y si son lo suficientemente largos como para tener más de una oración, deben dividirse en partes principal y de detalle). Sin embargo, los mensajes de detalle y sugerencia son más largos y pueden necesitar incluir varias oraciones. Para mantener la coherencia, deben seguir el estilo de oración completa incluso cuando solo hay una oración.

Utiliza minúsculas para la redacción de los mensajes, incluida la primera letra de un mensaje de error principal. Utiliza mayúsculas para los comandos SQL y las palabras clave si aparecen en el mensaje.

Justificación: Es más fácil hacer que todo se vea más consistente de esta manera, ya que algunos mensajes son oraciones completas y otros no.

Utiliza la voz activa. Utiliza oraciones completas cuando haya un sujeto que realice la acción (“A no pudo hacer B”). Utiliza un estilo de telegrama sin sujeto si el sujeto fuera el programa mismo; no utilices “yo” para referirte al programa.

Justificación: El programa no es humano. No pretendas lo contrario.

Utiliza el tiempo pasado si un intento de hacer algo falló, pero tal vez podría tener éxito la próxima vez (tal vez después de solucionar algún problema). Utiliza el tiempo presente si el fallo es ciertamente permanente.

Existe una diferencia semántica no trivial entre las oraciones de la forma:

could not open file "%s": %m

y:

cannot open file "%s"

La primera significa que el intento de abrir el archivo falló. El mensaje debería dar una razón, como “disco lleno” o “el archivo no existe”. El tiempo pasado es apropiado porque la próxima vez es posible que el disco ya no esté lleno o que el archivo en cuestión exista.

La segunda forma indica que la funcionalidad de abrir el archivo especificado no existe en absoluto en el programa, o que es conceptualmente imposible. El tiempo presente es apropiado porque la condición persistirá indefinidamente.

Justificación: De acuerdo, el usuario promedio no podrá sacar grandes conclusiones simplemente a partir del tiempo verbal del mensaje, pero dado que el lenguaje nos proporciona una gramática, deberíamos usarla correctamente.

Al citar el nombre de un objeto, indica de qué tipo de objeto se trata.

Justificación: De lo contrario, nadie sabrá a qué se refiere “foo.bar.baz”.

Los corchetes solo deben utilizarse (1) en las sinopsis de comandos para denotar argumentos opcionales, o (2) para denotar un índice de array.

Justificación: Cualquier otra cosa no corresponde al uso habitual ampliamente conocido y confundirá a la gente.

Cuando un mensaje incluye texto generado en otra parte, incrusta ese texto con este estilo:

could not open file %s: %m

Justificación: Sería difícil tener en cuenta todos los códigos de error posibles para pegar esto en una sola oración fluida, por lo que se necesita algún tipo de puntuación. También se ha sugerido poner el texto incrustado entre paréntesis, pero resulta antinatural si el texto incrustado es probablemente la parte más importante del mensaje, como suele ser el caso.

Los mensajes deben indicar siempre la razón por la que se produjo un error. Por ejemplo:

INCORRECTO: could not open file %s
MEJOR:      could not open file %s (I/O failure)

Si no se conoce ninguna razón, es mejor que corrijas el código.

No incluyas el nombre de la rutina que reporta el error en el texto del mismo. Tenemos otros mecanismos para averiguar eso cuando sea necesario, y para la mayoría de los usuarios no es información útil. Si el texto del error no tiene tanto sentido sin el nombre de la función, re redáctalo.

INCORRECTO: pg_strtoint32: error in "z": cannot parse "z"
MEJOR:      invalid input syntax for type integer: "z"

Evita también mencionar los nombres de las funciones llamadas; en su lugar, di qué intentaba hacer el código:

INCORRECTO: open() failed: %m
MEJOR:      could not open file %s: %m

Si realmente parece necesario, menciona la llamada al sistema en el mensaje de detalle. (En algunos casos, proporcionar los valores reales pasados a la llamada al sistema podría ser información adecuada para el mensaje de detalle).

Justificación: Los usuarios no saben qué hacen todas esas funciones.

Unable (Incapaz / No se puede).  “Unable” es casi la voz pasiva. Es mejor utilizar “cannot” o “could not”, según corresponda.

Bad (Malo / Erróneo).  Los mensajes de error como “bad result” son muy difíciles de interpretar de forma inteligente. Es mejor escribir por qué el resultado es “malo”, por ejemplo, “invalid format”.

Illegal (Ilegal).  “Illegal” representa una violación de la ley, el resto es “invalid”. Mejor aún, di por qué no es válido.

Unknown (Desconocido).  Intenta evitar “unknown”. Considera “error: unknown response”. Si no sabes cuál es la respuesta, ¿cómo sabes que es errónea? “Unrecognized” suele ser una mejor opción. Además, asegúrate de incluir el valor del que te estás quejando.

INCORRECTO: unknown node type
MEJOR:      unrecognized node type: 42

Buscar vs. Existir (Find vs. Exists).  Si el programa utiliza un algoritmo no trivial para localizar un recurso (por ejemplo, una búsqueda de ruta) y ese algoritmo falla, es justo decir que el programa no pudo “encontrar” (find) el recurso. Si, por otro lado, se conoce la ubicación esperada del recurso pero el programa no puede acceder a él allí, di que el recurso no “existe” (exist). Usar “encontrar” en este caso suena débil y confunde el asunto.

May vs. Can vs. Might.  “May” sugiere permiso (por ejemplo, "You may borrow my rake."), y tiene poco uso en la documentación o en los mensajes de error. “Can” sugiere habilidad (por ejemplo, "I can lift that log."), y “might” sugiere posibilidad (por ejemplo, "It might rain today."). El uso de la palabra adecuada aclara el significado y ayuda a la traducción.

Contracciones.  Evita las contracciones en inglés (como “can't”); utiliza “cannot” en su lugar.

No negativo (Non-negative).  Evita “non-negative” ya que es ambiguo sobre si acepta el cero. Es mejor utilizar “greater than zero” (mayor que cero) o “greater than or equal to zero” (mayor o igual que cero).

Escribe las palabras completas. Por ejemplo, evita:

Justificación: Esto mejorará la consistencia.

Ten en cuenta que los textos de los mensajes de error deben traducirse a otros idiomas. Sigue las pautas de Section 56.2.2 para evitar complicarles la vida a los traductores.