Загадочные сообщения об ошибках: вносим ясность

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

3К открытий3К показов

Попробуйте вспомнить, какие оригинальные и необычные сообщения об ошибках вам выдавали многочисленные программы и приложения, которыми вы пользуетесь. Наверняка у каждого из вас найдётся пара забавных примеров таких сообщений. В моём личном рейтинге на данный момент безусловный лидер — «Метод вернул что-то не то». Если существует шкала информативности сообщений, то приведённый пример по этой шкале стремится к нулю.

Здесь система, по сути, сообщает нам, что произошла ошибка. Больше никакой информации из этого текста мы не получим. Разве что узнаем, что где-то в недрах самой системы существует какой-то метод, который что-то не то вернул. Ценность этого знания для обычного пользователя нулевая.

Можно предположить, что этот текст — артефакт, оставшийся от процесса тестирования очередной функциональности. Некий флаг, оставленный разработчиком на этапе альфа-тестирования. Для программиста он явно имел какой-то смысл, но для обычного пользователя — совершенно бесполезен.

Давайте порассуждаем, каким должно быть идеальное сообщение об ошибке.

5 основных правил

В книге Сьюзан Уэйншенк «100 главных принципов дизайна» приведены основные правила написания информативного и полезного сообщения об ошибке:

  1. Расскажите пользователю, что он сделал.
  2. Объясните проблему.
  3. Объясните, как исправить ошибку.
  4. Используйте активный, а не пассивный залог.
  5. Приведите пример.

В книге есть пример того, как не надо писать сообщения об ошибке:

#402: до того как счёт может быть оплачен, необходимо, чтобы дата платежа была позднее, чем дата создания счёта.

После варианта «Метод вернул что-то не то» даже такое сообщение может показаться довольно информативным. Однако в нём есть что улучшить. Но для начала давайте в порядке эксперимента попробуем его ухудшить — разберёмся, как не надо писать сообщения об ошибках.

А ещё хуже можешь?

«Вы хотите отправить разработчикам отчёт об ошибке в приложении?»«Ok»«Ну и ябеда!»

Нам не привыкать — у нас за плечами многолетний опыт общения с разномастными продуктами отечественного софтостроения. Давайте уберём конкретику вовсе:

Счёт не может быть оплачен. Введены неправильные данные.

Чтобы ещё больше запутать пользователя, скроем от него причину ошибки:

Счёт не может быть оплачен.

Теперь приблизимся вплотную к нашему почти нулевому варианту:

Ошибка выполнения метода bill_payment.

Дальше для достижения антиидеала нам остаётся только убрать название метода и творчески преобразовать текст:

Неизвестная ошибка.

Интересно, не возникло ли у вас чувство дежавю, когда вы читали примеры в этом подразделе?

Добавляем информацию

В случае возникновения критической ошибки обновления:1. Установите причину ошибки.2. Устраните причину ошибки.Документация Microsoft

 

Теперь давайте двигаться в другую сторону по нашей шкале — будем постепенно улучшать текст сообщения, руководствуясь правилами Сьюзан Уэйншенк.

Загадочные сообщения об ошибках: вносим ясность 1

Напомню исходный вариант сообщения из книги:

#402: до того как счёт может быть оплачен, необходимо, чтобы дата платежа была позднее, чем дата создания счёта.

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

#402: Для оплаты счёта необходимо, чтобы дата платежа была позднее, чем дата создания счёта.

Теперь расскажем пользователю, что он сделал не так:

#402: Вы ввели неправильную дату платежа — она раньше, чем дата создания счёта. Для оплаты счёта необходимо, чтобы дата платежа была позднее, чем дата создания счёта.

Выделим суть проблемы в отдельное предложение и явно объясним пользователю, что он должен сделать, чтобы её решить.

#402: Ошибка оплаты счёта. Вы ввели неправильную дату платежа — она раньше, чем дата создания счёта. Измените дату платежа так, чтобы она была позднее даты создания счёта.

Наконец, приведём конкретный пример. В данном случае нам известны даты и мы их можем использовать в тексте:

#402: Ошибка оплаты счёта. Вы ввели неправильную дату платежа 25.07.2021 — она раньше, чем дата создания счёта 29.07.2021. Измените дату платежа так, чтобы она была позднее даты создания счёта 29.07.2021. Например, 30.07.2021.

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

Лучшее сообщение об ошибке

Ошибка выполнения метода: «Метод выполнился без ошибок».

Есть фразы, которые сразу хочется выписать на жёлтый стикер и приклеить где-то рядом с монитором. Одна из таких фраз: «Лучшее сообщение об ошибке — отсутствие сообщения об ошибке». Иными словами, часто бывает проще не допустить возможности возникновения ошибки, чем её описывать.

В нашем примере никто не мешает разработчику сделать две вещи:

  1. При смене даты счёта очистить поле с датой платежа.
  2. В интерфейсе запретить ввод даты платежа позже заданной даты счёта.

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

К сожалению, таким простым способом решить проблему удаётся не всегда. Мы не можем полностью обезопасить приложение от возникновения ошибок. Но в наших силах сделать сообщения об ошибках более информативными и полезными.

А с какими загадочными сообщениями об ошибках сталкивались вы?

Следите за новыми постами
Следите за новыми постами по любимым темам
3К открытий3К показов