Сообщение должно быть кратким, фактическим и не должно содержать ссылок на детали реализации, такие как конкретные имена функций. “Краткое” означает, что оно должно помещаться на одной строке в обычных условиях. Используйте дополнительное сообщение, если нужно, чтобы основное сообщение было кратким, или если вам нужно упомянуть детали реализации, такие как конкретный системный вызов, который завершился неудачно. И основное, и дополнительное сообщения должны быть фактическими. Используйте подсказку для предложений о том, что нужно сделать, чтобы исправить проблему, особенно если предложение не всегда применимо.

Например, вместо:

IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(plus a long addendum that is basically a hint)

записать:

Primary:    could not create shared memory segment: %m
Detail:     Failed syscall was shmget(key=%d, size=%u, 0%o).
Hint:       the addendum

Обоснование: сохранение основного сообщения коротким помогает сделать его кратким и позволяет клиентам располагать пространством экрана с предположением, что одна строка достаточна для сообщений об ошибках. Подробности и подсказки могут быть перенесены в режим с подробностями или, возможно, во всплывающее окно с подробностями об ошибке. Кроме того, подробности и подсказки обычно подавляются в журнале сервера, чтобы сэкономить место. Ссылки на детали реализации лучше избегать, так как от пользователей не ожидается знание этих деталей.

Не делайте никаких конкретных предположений о форматировании в текстах сообщений. Ожидайте, что клиенты и журнал сервера будут переносить строки, чтобы соответствовать своим собственным потребностям. В длинных сообщениях символы перехода строки (\n) могут использоваться для обозначения предлагаемых разрывов абзацев. Не заканчивайте сообщение символом перехода строки. Не используйте табуляцию или другие символы форматирования. (В контексте отображения ошибок символы перехода строки автоматически добавляются для разделения уровней контекста, таких как вызовы функций).

Обоснование: Сообщения не всегда отображаются на терминальных дисплеях. В графических интерфейсах или браузерах эти инструкции форматирования, в лучшем случае, игнорируются.

Английский текст должен использовать двойные кавычки при необходимости цитирования. Текст на других языках должен последовательно использовать один вид кавычек, который соответствует традициям публикации и компьютерному выводу других программ.

Обоснование: Выбор двойных кавычек вместо апострофов в значительной степени произволен, но обычно предпочтительнее. Некоторые предлагают выбирать вид кавычек в зависимости от типа объекта в соответствии с SQL-конвенциями (то есть, строки заключаются в апострофы, идентификаторы - в двойные кавычки). Но это внутренняя техническая проблема языка, с которой многие пользователи даже не знакомы, она не масштабируется на другие виды кавычек, не переводится на другие языки и, кроме того, бессмысленна.

Всегда используйте кавычки для ограничения имен файлов, идентификаторов, предоставляемых пользователем, и других переменных, которые могут содержать слова. Не используйте их для выделения переменных, которые не будут содержать слов (например, имен операторов).

В бэкенде есть функции, которые автоматически заключают свой вывод в двойные кавычки при необходимости (например, format_type_be()). Не добавляйте дополнительные кавычки вокруг вывода таких функций.

Обоснование: Объекты могут иметь имена, которые создают неоднозначность при встраивании в сообщение. Будьте последовательными в обозначении начала и конца подключаемого имени. Но не стоит перегружать сообщения ненужными или дублирующими кавычками.

Правила отличаются для основных сообщений об ошибках и для детальных/подсказок сообщений:

Основные сообщения об ошибках: не пишите первую букву с заглавной. Не заканчивать сообщение точкой. Ни в коем случае не заканчивать сообщение восклицательным знаком.

Сообщения с подробностями и подсказками: рекомендуется использовать полные предложения и заканчивать их точкой. Первое слово предложения писать с заглавной буквы. После точки поставить два пробела, если следует еще одно предложение (для английского текста; это может быть неприемлемо для других языков).

Строки контекста ошибки: не писать первую букву с заглавной и не заканчивать строку точкой. Строки контекста как правило не должны быть полными предложениями.

Rationale: Избегание знаков препинания облегчает встраивание сообщения в различные грамматические контексты клиентских приложений. Часто первичные сообщения все равно не являются грамматически полными предложениями. (А если они достаточно длинные, чтобы быть более чем одним предложением, их следует разделить на первичную и детальную части). Однако сообщения с деталями и подсказками более длинные и могут содержать несколько предложений. Для согласованности они должны следовать стилю полного предложения, даже если есть только одно предложение.

Используйте строчные буквы для формулировки сообщений, включая первую букву основного сообщения об ошибке. Используйте заглавные буквы для команд SQL и ключевых слов, если они появляются в сообщении.

Обоснование: Так проще сделать все более согласованным, поскольку некоторые сообщения являются полными предложениями, а некоторые - нет.

Используйте активный залог. Используйте полные предложения, когда есть действующий субъект (“A не может сделать B”). Используйте телеграммный стиль без субъекта, если субъектом является сама программа; не используйте “I” для программы.

Обоснование: Программа не является человеком. Не притворяйтесь иначе.

Используйте прошедшее время, если попытка что-то сделать не удалась, но возможно, что в следующий раз она может быть успешной (возможно, после устранения некоторой проблемы). Используйте настоящее время, если неудача явно является постоянной.

Существует неочевидное семантическое различие между следующими предложениями:

could not open file "%s": %m

и

cannot open file "%s"

Первое означает, что попытка открыть файл не удалась. Сообщение должно содержать причину, такую как “недостаточно места на диске” или “файл не существует”. Прошедшее время является уместным, потому что в следующий раз диск может быть не заполнен или файл может существовать.

Вторая форма указывает на то, что функциональность открытия указанного файла в программе отсутствует полностью или что это концептуально невозможно. Настоящее время является уместным, поскольку условие будет сохраняться бесконечно.

Обоснование: Конечно, обычный пользователь не сможет сделать большие выводы только по времени сообщения, но поскольку язык предоставляет нам грамматику, мы должны использовать ее правильно.

При цитировании имени объекта укажите, какого рода объект это.

Обоснование: В противном случае никто не будет знать, на что ссылается “foo.bar.baz”.

Квадратные скобки следует использовать только (1) в описаниях команд для обозначения необязательных аргументов или (2) для обозначения индекса массива.

Обоснование: Все остальное не соответствует широко известному обычаю использования и будет сбивать людей с толку.

Когда сообщение содержит текст, сгенерированный в другом месте, вставьте его в этом стиле:

could not open file %s: %m

Обоснование: Было бы сложно учесть все возможные коды ошибок, чтобы вставить это в одно гладкое предложение, поэтому требуется какой-то вид пунктуации. Предлагалось также помещать встроенный текст в скобки, но это неестественно, если встроенный текст, как часто бывает, является самой важной частью сообщения.

Сообщения всегда должны указывать причину возникновения ошибки. Например:

BAD:    could not open file %s
BETTER: could not open file %s (I/O failure)

Если причина неизвестна, лучше исправить код.

Не включайте имя процедуры отчетности в текст ошибки. У нас есть другие механизмы для определения этого при необходимости, и для большинства пользователей это не полезная информация. Если текст ошибки не имеет смысла без имени функции, переформулируйте его.

BAD:    pg_strtoint32: error in "z": cannot parse "z"
BETTER: invalid input syntax for type integer: "z"

Избегать упоминания названий вызываемых функций; вместо этого скажите, что код пытался сделать:

BAD:    open() failed: %m
BETTER: could not open file %s: %m

Если это действительно необходимо, упомяните системный вызов в детальном сообщении. (В некоторых случаях предоставление фактических значений, переданных в системный вызов, может быть соответствующей информацией для детального сообщения).

Обоснование: Пользователи не знают, что делают все эти функции.

Unable.  “Unable” - это почти пассивный залог. Лучше использовать “cannot” или “could not”, в зависимости от ситуации.

Bad.  Сообщения об ошибках, такие как “плохой результат”, действительно трудно интерпретировать адекватно. Лучше написать, почему результат “плохой”, например, “неверный формат”.

Illegal.  “Незаконный (illegal)” означает нарушение закона, остальное является “недействительным”. Лучше всего объяснить, почему оно недействительно.

Неизвестный тип.  Постарайтесь избегать слова “unknown”. Рассмотрите “error: unknown response”. Если вы не знаете, что это за ответ, откуда вы знаете, что он ошибочен? “Unrecognized” часто является более подходящим выбором. Также убедитесь, что включили значение, на которое выдается ошибка.

BAD:    unknown node type
BETTER: unrecognized node type: 42

Find или Exists.  Если программа использует нетривиальный алгоритм для поиска ресурса (например, поиск по пути) и этот алгоритм не срабатывает, можно сказать, что программа не может “найти” ресурс. Если же ожидаемое местоположение ресурса известно, но программа не может получить к нему доступ, то говорят, что ресурс не “существует”. В данном случае использование слова “найти” звучит слабо и вводит в заблуждение.

May, Can или Might.  “May” предполагает разрешение (например, "Вы можете взять мою грабли"), и имеет мало пользы в документации или сообщениях об ошибках. “Can” предполагает способность (например, "Я могу поднять этот бревно."), и “might” предполагает возможность (например, "Сегодня может пойти дождь."). Использование правильного слова уточняет значение и помогает при переводе.

Сокращения.  Избегать сокращений, таких как “can't”; вместо этого используйте “cannot”.

Non-negative.  Избегайте использования термина “non-negative (неотрицательный)”, так как он неоднозначен в отношении принятия значения ноль. Лучше использовать термин "больше нуля" или "больше или равно нулю".

Полностью раскрывать слова. Например, избегать:

Обоснование: Это улучшит согласованность.

Следует иметь в виду, что тексты сообщений об ошибках необходимо переводить на другие языки. Следуйте рекомендациям в Раздел 54.2.2, чтобы не создавать проблем для переводчиков.