Руководство по описанию ошибок

Зачем это читать

Все просто: чем более эффективно составлен отчет об ошибке, тем более вероятно, что она будет исправлена разработчиком.

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

Как составить эффективный отчет

Отчет об ошибке эффективен, если приводит к ее исправлению. Эффективный отчет отличается двумя свойствами:

  1. Воспроизводимость. Если инженер не убедится в наличии ошибки, она вероятнее всего будет отмечена как "WORKSFORME" (не подтверждается тестами) или "INVALID" (неверное сообщение). Здесь важна каждая деталь.

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

    [ Пример ]

Допустим, вы тестируете веб-обозреватель. Он свалился при обращении к foo.com, и вы пишете отчет об ошибке:

НЕПРАВИЛЬНО: "Программа рухнула. Кажется, на www.foo.com. Я играю в гольф с Биллом Гейтсом, поэтому если вы не исправите проблему, я при встрече ему пожалуюсь. Кстати, кнопка возврата выглядит как дохлая крыса. Б-р-р-р! И еще: страничку моей бабушки в вашей программе смотреть невозможно. Thx 4 UR help."

ПРАВИЛЬНО: "Фатальная ошибка каждый раз при обращении к www.foo.com, версия программы от 25.02.2002, система Windows 2000. Проблема воспроизводима также в Linux, с версией от 24.02.2002.

Ошибка происходит про отображении логотипа Foo наверху страницы. Методом деления страницы найдена проблемная ссылка: ошибка исчезает, если удалить атрибут "border=0":

<IMG SRC="http://www.foo.com/images/topics/topicfoos.gif" width="34" height="44" border="0" alt="News"> "

Как ввести эффективный отчет в Bugzilla:

Прежде, чем добавлять ошибку, используйте форму поиска Bugzilla на случай, если обнаруженный вами дефект уже известен. Регистрируя давно известную проблему в 37 раз, вы наверняка беспокоите программиста попусту. (Раздраженный программист исправляет меньше ошибок.)

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

Если вы обнаружили незарегистрированную ранее ошибку в текущей версии программы, пишите отчет в Bugzilla:

  1. На главной странице Bugzilla выберите "Регистрация новой ошибки".
  2. Выберите продукт, в котором обнаружена ошибка.
  3. Введите ваш адрес электронной почты, пароль и нажмите кнопку "Login". (Если у вас еще нет пароля, не заполняйте это поле и нажмите кнопку "E-mail me a password". Вы вскоре получите пароль по электронной почте.)

Теперь перейдем к заполнению формы:

Где обнаружена ошибка?

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

Версия: В какой версии продукта обнаружена ошибка?
(При наличии версий)

Компонент: В каком компоненте продукта проявляется ошибка?
Требуется указать наименование компонента. (Если вы затрудняетесь с выбором, нажмите ссылку "Компонент". Появится краткое описание компонентов продукта.)

OS: В какой операционной системе проявляется ошибка? (Например: Linux, Windows 2000, Mac OS 9.)
Если известно, что ошибка происходит в любой системе, выберите 'All'. В противном случае выберите операционную систему, либо "Other" -- если вашей системы нет в списке.

Насколько серьезна ошибка?

Серьезность: Насколько опасны последствия ошибки?
Значение по умолчанию -- 'normal'. Если вы затрудняетесь с выбором, нажмите ссылку "Серьезность". Появится описание значений шкалы опасности ошибок.

Кто будет заниматься ошибкой?

Ответственный: Кто будет отвечать за исправление ошибки?
При регистрации ошибки Bugzilla автоматически назначает ответственного за компонент. Если необходимо указать другого инженера, введите его email. (Список ответственных можно увидеть на странице описания компонентов.)

Подписка: Кто еще должен быть оповещен об изменениях состояния ошибки?
Перечислите адреса тех, кто должен получать по email отчеты об изменениях состояния ошибки. Адреса разделяются пробелами или запятыми. Количество адресов не ограничено, но все должны быть зарегистрированы ранее в Bugzilla.

Что еще известно об ошибке?

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

Пример эффективной аннотации: "Сбой при установке драйвера PCMCIA для 3c589C на Toshiba Tecra 780DVD". "Сбой программы" или "проблема при установке" -- примеры неудачных аннотаций.

[ Подробнее ]

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

Общая характеристика: Более детальное описание ошибки.

В версии для Mac OS выделение мышью на любой странице вызывает сбой в
функции NSGetFactory

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

1) Открыть любую страницу. (Например, используемую по умолчанию
resource:/res/samples/test0.html)
                          
2) Выделите текст мышью. (Точнее, нажав клавишу мыши в любой точке 
страницы, тяните указатель вниз к границе окна.)                   

Результат ошибки: Что произошло после описанных шагов.

Крах приложения с распечаткой значений регистров (анализ стека 
из MacsBug прилагается).

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

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

Версия и платформа: Дата и платформа версии, в которой впервые замечена ошибка.

Релиз от 15.03.2002 для Mac OS 9.0

Другие версии и платформы: Воспроизводимость ошибки на других платформах и версиях (или других продуктах, если это уместно).

- Также воспроизводится на:
    Mozilla (релиз от 2002-03-15 на Windows NT 4.0) 
                                    
- Не происходит,
    Mozilla (релиз от 2002-03-15 на Red Hat Linux; функция не
             поддерживается)        
    Internet Explorer 5.0 (из комплекта Windows NT 4.0)        
    Netscape Communicator 4.5 (из комплекта Mac OS 9.0)

Дополнительная информация: Любая другая отладочная информация. Для случаев аварийного завершения:

  • Win32: Если ошибка регистрируется Dr. Watson, укажите тип сбоя и имя модуля (например, ошибка защиты в модуле apprunner.exe)
  • Mac OS: при использовании MacsBug, укажите тип сбоя и трассировку стека:
*** MACSBUG STACK CRAWL OF CRASH (Mac OS)
Calling chain using A6/R1 links 
    Back chain  ISA  Caller 
    00000000    PPC  0BA85E74   
    03AEFD80    PPC  0B742248   
    03AEFD30    PPC  0B50FDDC  NSGetFactory+027FC
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

Готово!

Еще раз проверьте всю указанную вами информацию, нажмите кнопку "Сохранить" и ваш отчет попадет в базу данных Bugzilla.


Подробнее об эффективных отчетах об ошибках

1. Советы общего характера

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

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

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

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

2. Как и для чего пишутся хорошие аннотации

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

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

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

Например, ошибку, озаглавленную "Перетаскивание иконки из списка в gnome-terminal не вставляет полный путь" можно найти, указав "спис", "terminal", или "путь". Тот же поиск не найдет ошибки, озаглавленной "Не вставляет при перетаскивании".

Спросите себя: "Можно ли понять ошибку по одной только аннотации?". Если ответ положительный -- вы написали прекрасную аннотацию.

Не пишите заголовков наподобие этих:

  1. "Не ставится" -- Почему не устанавливается? Что происходит, если попробовать установить?
  2. "Работает очень медленно" -- ...и что надо сделать, чтобы это произошло?
  3. "Кнопка возврата не работает" -- В смысле? Вообще никогда?

Удачные заголовки:

  1. "Обновление до 1.0 не работает, если установлен пакет Mozilla M18" -- объясняет проблему и контекст.
  2. "Установка RPM 4 завершается аварийно при запуске в Red Hat 6.2 (RPM 3)" -- объясняет что именно случилось и где.

(Автор: Eli Goldberg. Дополнения: Claudius Gayle, Gervase Markham, Peter Mock, Chris Pratt, Tom Schutter и Chris Yeh. Присылайте ваши конструктивные замечания. Русский перевод -- Виталий Федрушков.)