Как написать хорошие сообщения об ошибках?

Вы имеете в виду доступ к пользователю или в файле журнала для персонала администраторов / разработчиков?

Я считаю, что в целом важны:

• Отметка времени
• Уровень опасности
• какие пошла не так
• Ответьте на вопросы «нужно ли мне действовать?» и "если да, то какое действие?"
• детализация на уровне разработчика (не заметно, если видна пользователю)
• согласованный формат и условия

Я думаю, что все это важно, но известность будет меняться в зависимости от аудитории (как указывает dmckee). Еще один совет (в общем) - ответить на 5 Вт (кто, что и т. д.)

Для конечных пользователей: скажите пользователю, что делать. Следует ли пользователю изменить какое-либо значение ввода, повторить попытку через 5 минут или вызвать в службу поддержки?

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

Пример:
«К сожалению, файл не может быть открыт. Убедитесь, что файл еще не открыт другой программой, и повторите попытку».

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

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

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

Хорошее сообщение об ошибке для пользователя:

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

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

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

К тому, что уже было сказано, я бы добавил:

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

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

Сообщения об ошибках должны:

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

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

Мы обнаружили, что когда сообщения об ошибках содержат код ошибки, это помогает в технической поддержке. Когда пользователи возвращают сообщения об ошибках в службу поддержки, они часто путают или неверно сообщают словесные сообщения об ошибках. Но если сообщение содержит номер ошибки, они очень хорошо сообщают точную ошибку, например: «Я получил ошибку 8512 при попытке распечатать отчет».

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

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

Во-первых, требования к сообщениям конечного пользователя:

• Хочет выполнить задание
• Хочет знать о решениях, а не о проблемах
• На самом деле не хочет видеть или читать сообщения об ошибках.

Далее, требования к сообщениям техников службы поддержки:

• Хочет быть активным, а не реактивным
• Не хочет столкнуться с проблемой «кирпичной стены»
• Не хочет, чтобы его заваливали сообщениями.

Наконец, требования к сообщениям поддержки разработчиков:

• Требуется простая ментальная модель для использования вашего кода
• Ожидает, что ваш компонент будет «просто работать»
• Требуется полезная информация, когда она не работает.

Пример сообщения об ошибке, которое очень плохо для конечного пользователя, но может быть разумным для разработчика, - «Кэш задержки столкнулся с исходящими заголовками». :-)

Обычно стоит указать на общую причину проблемы, так как это поможет пользователю в 99,9% случаев ошибки.

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

«Произошло распознанное исключение. Это может быть проблема с конфигурацией»

и еще один для неожиданного:

«Произошла непредвиденная ошибка».

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

Здесь можно отметить несколько разных контекстов (хотя я уверен, что об этом упоминалось снова и снова):

1) Если мы говорим о веб-сайте, который должен выдать сообщение «Ой, произошло что-то плохое», тогда должен быть простой язык, чтобы сообщить пользователю, что произошла ошибка, попробуйте еще раз, и если все еще есть проблемы, обратитесь в службу поддержки по адресу бла бла бла...

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

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

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

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

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

С точки зрения пользователей.

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

Сообщения об ошибках имеют три основные функции:

1. Привлекайте внимание - во-первых, чтобы убедиться в эффективности, пользователь должен это увидеть

• красный цвет)
• шрифт (размер, вес)
• местоположение (вверху страницы, окно предупреждения)
• фокус (символ!, контур поля ввода)
• согласованность (используйте одинаковый формат для сообщений об ошибках во всем приложении)

2. Опишите ошибку. - сообщить пользователю, что пошло не так

• использовать простой язык, понятный пользователю
• используйте объективный голос, не обвиняйте пользователя
• быть кратким

3. Предложите восстановление - дать полезные предложения по исправлению ошибки и продолжить

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

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

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

Одна вещь, которая может повредить мою нервную систему, - это когда в сообщении об ошибке используется слово ИЛИ. «Файл не найден ИЛИ нет разрешения ИЛИ диск заполнен ИЛИ у вашей собаки сильная головная боль ИЛИ ...» Пользователь В самом деле должен знать, какая из возможных причин ошибки произошла. Программисты, пожалуйста, избегайте OR в сообщениях об ошибках.

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

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

Хорошее сообщение об ошибке состоит из трех частей:

1. Эта проблема - объясняет, что произошла ошибка;
2. Причина - объясняет причину проблемы;
3. Решение - объясняет, как решить проблему.

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

Но обратное неверно. Сложно превратить небольшое сообщение в сообщение, которое четко объясняет проблему, причину и решение проблемы. Вы будете постоянно редактировать свои мысли, чтобы сообщение оставалось небольшим, и в какой-то момент вас заблокируют. Да, я сталкивался с этой проблемой несколько раз, поэтому я знаю, насколько это тяжело.

Убедившись, что ваше сообщение содержит все эти три части, пора его просмотреть. Вам нужно отредактировать его, чтобы убедиться, что он:

1. Ориентирован на пользователя - избегайте жаргона и слов, которые будут непонятны вашей аудитории;
2. Прямо - как сказал Уильям Странк: «Приведите утверждения в положительную форму. Избегайте скучных, бесцветных, нерешительных и уклончивых слов »;
3. Опускает ненужные слова - вырезать, вырезать, вырезать.

Как видите, этот фреймворк прост и не требует особых размышлений.

Источники:

• http://www.joaofn.com/post/how-to-write-error-messages/
• http://blogs.msdn.com/b/brada/archive/2004/01/28/64255.aspx
• http://msdn.microsoft.com/en-us/library/dn742471.aspx