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

Question

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

Я ненадолго искал и не смог найти двойную ветку. Хорошо, есть на это. Спасибо всем.

Answer 1

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

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

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

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

Answer 2

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

Я думаю, что в целом это важно:

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

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

Answer 3

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

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

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

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

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

Answer 4

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

Answer 5

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

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

Answer 6

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

Для сообщений об ошибках есть три основные функции:

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

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

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

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

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

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

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

Answer 7

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

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

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

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

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

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

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

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

Answer 8

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

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

Answer 9

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

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

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

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

Answer 10

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

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

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