Как эффективно сообщать об ошибках

Автор: Саймон Тэтхем

1999

Введение

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

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

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

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

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

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

"Это не работает".

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

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

В этом эссе много правил. Ни одно из них не является абсолютным. Разные программисты предпочитают разные способы сообщения об ошибках. Если программа идёт со своим набором правил сообщения об ошибках, прочитайте их. Если правила, которые идут с программой противоречат правилам в этом эссе, следуйте тем, которые идут с программой!

Если вы не сообщаете об ошибке, а просто просите о помощи в использовании программы, вам стоит рассказать, где вы уже искали ответ на ваш вопрос. ("Я смотрел в главе 4 и разделе 5.2, но не смог найти что-либо, что сказало бы мне возможно ли это") Это позволит программисту узнать, где люди ожидают найти ответ, таким образом, он может сделать документацию более удобной.

"Покажите мне".

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

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

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

"Покажите мне как показать себе".

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

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

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

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

"У меня работает. Так что неправильно?"

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

Таким образом, также опишите, что произошло. Опишите точно, что вы увидели. Опишите, почему вы думаете, что-то, что вы увидели неправильно; еще лучше опишите точно, что вы ожидали увидеть. Если вы говорите "и тогда она сделала это неправильно", вы опускаете важную информацию

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

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

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

Если вы пользуетесь Unix, программа может произвести дамп ядра (core dump). Дампы ядра - важные источники улик, поэтому не выбрасывайте их. C другой стороны, большинство программистов не любят получать гигантские файлы с дампами по электронной почте без предупреждения, поэтому спросите, перед тем, как отправлять их кому-либо. Также, имейте ввиду, что дампы содержат запись всего состояния программы: любые "секреты" (возможно, программа содержит личное сообщение или имеет дело с конфиденциальными данными) могут содержаться в дампах.

"Затем я попробовал . . ."

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

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

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

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

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

"Я думаю, что тахионная модуляция, должно быть, плохо поляризована".

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

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

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

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

Я уверен, что с врачом он бы так не поступал. "Доктор, мне нужен рецепт Гидройойодина." Люди знают, что это не надо говорить врачу: они говорят симптомы, свои неудобства, боли, сыпь и жар, и вы позволите врачу сделать диагноз, что это за проблема и что с ней делать. Иначе, врач объявит вас ипохондриком или сумасшедшим, и это будет правильно.

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

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

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

"Забавно, оно делало так секунду назад".

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

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

Также, если вы можете воспроизвести ошибку, а программист не может, это может быть потому, что ваш компьютер и его компьютер в чем-то различаются и это различие приводит к ошибке. Однажды у меня была программа, которая сворачивалась в маленький шарик в верхнем левом углу экрана, и сидела там и дулась. Но она это делала только при разрешении 800x600; все было хорошо на моем 1024x768 мониторе.

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

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

"Тогда я загрузил диск в свой Windows . . ."

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

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

• Будьте конкретны. Если вы можете сделать что-то двумя способами, укажите, каким вы воспользовались. "Я выбрал Загрузить" может значить "Я щелкнул по кнопке Загрузить" или "Я нажал Alt+З". Скажите, что вы сделали. Иногда это имеет значение.
• Будьте многословны. Лучше дать больше информации, чем меньше. Если вы сказали слишком много, программист может игнорировать какие-то части. Если вы сказали слишком мало, он должен вернуться и задать еще вопросы. Одно из сообщений об ошибке, которое я получил, состояло из одного предложения. Каждый раз, когда я просил больше информации, сообщивший отвечал мне одним предложением. Получение полезного объема информации заняло у меня несколько недель, поскольку прибавлялось каждый раз по одному небольшому предложению.
• Будьте осторожны с местоимениями. Не используйте слов вроде "это" или "окно" когда неясно, что они означают. Рассмотрим вот это: "Я запустил приложение Foo. Оно выкинуло окно с предупреждением. Я попытался закрыть его, и оно упало". Неясно, что пользователь пытался закрыть. Пытался ли он закрыть окно с предупреждением или приложение Foo целиком? Это большая разница. Вместо этого вы можете сказать "Я запустил приложение Foo, которое выкинуло окно с предупреждением. Я попытался закрыть окно с предупреждением, и приложение Foo упало". Это длиннее и с повторениями, но, также, яснее и его труднее неправильно понять.
• Прочитайте то, что вы написали. Сами прочитайте сообщение, и посмотрите считаете ли вы сами, что оно ясное. Если вы привели последовательность действий, приводящую к сбою, попытайтесь выполнить ее сами чтобы убедиться в том, что вы не пропустили какой-нибудь шаг.

Резюме

• Первая задача сообщения об ошибке - позволить программисту увидеть сбой собственными глазами. Если вы не можете быть с ним, чтобы воспроизвести сбой перед программистом, дайте ему детальные инструкции, чтобы он смог воспроизвести сбой самостоятельно.
• В случае если первая задача не выполнена и программист не может увидеть сбой сам, вторая задача сообщения об ошибке - описать, что произошло неправильно. Опишите все детально. Определите, что вы увидели. Также определите, что вы ожидали увидеть. Запишите сообщения об ошибках, особенно если в них есть числа.
• Если компьютер делает что-то неожиданное, замрите. Не делайте ничего до тех пор, пока вы не успокоитесь, и не делайте ничего, что, как вы думаете, может быть опасным.
• Конечно, попытайтесь продиагностировать сбой, если вы считаете, что можете это сделать, но даже в этом случае следует также сообщить симптомы.
• Будьте готовы предоставить дополнительную информацию, если это потребуется программисту. Он бы не спрашивал, если бы это не было ему нужно. Он не является намеренно раздражающим (неудобным) Пусть номера версий будут у вас на кончиках пальцев потому, сто они, вероятно, понадобятся.
• Пишите ясно. Скажите, что вы имеете в виду и убедитесь в том, что это не может быть истолковано неправильно.
• Прежде всего, будьте точны. Программисты любят точность.