Руководство по стилю сообщений об ошибках

Это руководство по стилю предлагается в надежде на поддержание последовательного, удобного для пользователя стиля во всех сообщениях, генерируемых PostgreSQL.

Что куда идет

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

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

IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m (плюс длинное добавление, которое по сути является подсказкой)

пишите:

Основное: не удалось создать сегмент общей памяти: %m
Детально: неудачным системным вызовом был shmget(key=%d, size=%u, 0%o).
Подсказка: дополнение

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

Форматирование

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

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

Кавычки

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

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

Использование кавычек

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

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

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

Грамматика и пунктуация

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

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

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

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

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

Верхний регистр и нижний регистр

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

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

Избегайте пассивного залога

Используйте активный залог. Используйте полные предложения при наличии действующего субъекта ("А не смог сделать Б"). Используйте стиль телеграммы без подлежащего, если подлежащим является сама программа; не используйте "я" для обозначения программы.

Обоснование: Программа - не человек. Не делайте вид, что это не так.

Настоящее и прошедшее время

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

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

не удалось открыть файл "%s": %m

и:

невозможно открыть файл "%s"

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

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

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

Тип объекта

При цитировании названия объекта укажите, что это за объект. Обоснование: Иначе никто не будет знать, к чему относится "foo.bar.baz".

Скобки

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

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

Сборка сообщений об ошибках

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

не удалось открыть файл %s: %m

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

Причины ошибок

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

ПЛОХО: не удалось открыть файл %s
ЛУЧШЕ: не удалось открыть файл %s (сбой ввода-вывода)

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

Имена функций

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

ПЛОХО: pg_strtoint32: ошибка в "z": не удалось разобрать "z"
ЛУЧШЕ: неверное значение для целого числа: "z"

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

ПЛОХО: ошибка в open(): %m
ЛУЧШЕ: не удалось открыть файл %s: %m

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

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

Сложные слова, которых следует избегать

Unable (Невозможно). "Unable" - это почти пассивный залог. Лучше использовать "невозможно" или "не удалось", в зависимости от ситуации.

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

Illegal (Незаконный). "Незаконный" означает нарушение закона, остальное - "недействительный". А еще лучше - скажите, почему это недействительно.

Unknown (Неизвестный). Старайтесь избегать слова "неизвестно". Рассмотрите вариант "ошибка: неизвестный ответ". Если не знать, что это за ответ, как узнать, что он ошибочный? "Нераспознанный" часто является лучшим выбором. Также не забудьте указать значение, на которое жалуются.

BAD: неизвестный тип узла
BETTER: нераспознанный тип узла: 42

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

May (разрешено) vs. Can (можно) vs. Might (Возможно). "Может" предполагает разрешение и мало используется в документации или сообщениях об ошибках. "Can" предполагает способность (например, "I can lift that log."), а "might" предполагает возможность (например, "It might rain today."). Использование подходящего слова проясняет смысл и помогает при переводе.

Сокращения. Избегайте сокращений, например «can't»; вместо это напишите «cannot».

Неотрицательный. Избегайте слова "неотрицательный", поскольку оно неоднозначно в отношении того, принимает ли оно ноль. Лучше использовать "больше нуля" или "больше или равно нулю".

Правильное написание

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

• spec;
• stats;
• parens;
• auth;
• xact.

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

Локализация

Не забывайте, что тексты сообщений об ошибках необходимо переводить на другие языки. Чтобы не усложнять жизнь переводчикам, следуйте рекомендациям в разделе «Рекомендации по написанию сообщений»