Користувальницькькі налаштування

Налаштування сайту


uk:bugreport

Розбіжності

Тут показані розбіжності між вибраною ревізією та поточною версією сторінки.

Посилання на цей список змін

uk:bugreport [2012/11/08 22:15] (поточний)
Рядок 1: Рядок 1:
 +===== How to Report Bugs Effectively =====
  
 +==== Introduction ====
 +
 +Anybody who has written software for public use will probably have received at least one bad bug report. Reports that say nothing ("It doesn'​t work!"​);​ reports that make no sense; reports that don't give enough information;​ reports that give wrong information. Reports of problems that turn out to be user error; reports of problems that turn out to be the fault of somebody else's program; reports of problems that turn out to be network failures. ​
 +
 +Існує причина,​ по якій технічну підтримку вважають роботою,​ якої огидно займатися,​ і ця причина - погані повідомлення про помилки. Однак не всі повідомлення про помилки такі відразливі:​ я підтримую вільне ПЗ, коли не заробляю на життя і іноді я отримую дивні, ясні інформативні повідомлення. ​
 +
 +У цьому есе я спробую ясно сформулювати,​ що робить повідомлення про помилку хорошим. В ідеалі я хотів би, щоб усі в світі прочитали цей нарис перед тим, як повідомляти будь-кому про помилки. Безумовно,​ мені б хотілося,​ щоб усі, хто повідомляє про помилки мені, прочитали його. ​
 +
 +Коротенько,​ мета повідомлення про помилку - дозволити програмістові побачити перед собою, як програма дає збій. Ви можете або показати це персонально,​ або дати точні і детальні інструкції про те, як зробити,​ щоб програма зламалася. Якщо вони зможуть добитися збою, вони спробують зібрати додаткову інформацію до тих пір, поки не дізнаються причину. Якщо вони не зможуть добитися збою, вони повинні запитувати вас для того, щоб зібрати цю інформацію. ​
 +
 +У повідомленнях про помилки постарайтеся чітко визначити,​ що є реальними фактами ("Я був за комп'​ютером і це трапилося"​),​ а що - припущеннями ("Я думаю, що проблема може бути в цьому"​). Опустіть припущення,​ якщо хочете,​ але не опускайте факти. ​
 +
 +Коли ви повідомляєте про помилку,​ ви це робите тому, що хочете,​ щоб помилка була виправлена. Немає сенсу в тому, щоб лаяти програмістів або свідомо не надавати їм допомогу:​ це може бути їхня помилка і ваша проблема,​ і ви можете на них сердитися,​ і ви можете бути правими в тому, що гнівайтесь на них, але помилка буде виправлена ​​швидше,​ якщо ви допоможете їм, надаючи всю інформацію,​ яка їм потрібна. Також пам'​ятайте,​ що якщо програма безкоштовна,​ автор надає вам її з доброти,​ тому якщо занадто багато людей занадто грубі з ним, то він може перестати бути добрим. ​
 +
 +==== "It doesn'​t work." ====
 +
 +Give the programmer some credit for basic intelligence:​ if the program really didn't work at all, they would probably have noticed. Since they haven'​t noticed, it must be working for them. Therefore, either you are doing something differently from them, or your environment is different from theirs. They need information;​ providing this information is the purpose of a bug report. More information is almost always better than less. 
 +
 +Багато програм,​ особливо безкоштовних,​ публікують списки відомих помилок. Якщо ви можете знайти список відомих помилок,​ варто його прочитати,​ щоб подивитися,​ чи є помилка,​ яку ви тільки що виявили відомої чи ні. Якщо вона вже відома,​ ймовірно не варто її повідомляти,​ але якщо ви думаєте,​ що у вас є більше інформації,​ ніж в повідомленні про помилку в списку,​ ви все одно можете зв'​язатися з програмістом. Їм буде легше виправити помилку,​ якщо ви зможете дати їм відомості,​ яких у них ще немає. ​
 +
 +У цьому есе багато правил. Жодне з них не є абсолютним. Різні програмісти віддають перевагу різні способи повідомлення про помилки. Якщо програма йде зі своїм набором правил повідомлення про помилки,​ прочитайте їх. Якщо правила,​ які йдуть з програмою суперечать правилам в цьому есе, дотримуйтесь тим, які йдуть з програмою! ​
 +
 +Якщо ви не повідомляєте про помилку,​ а просто просите про допомогу у використанні програми,​ вам варто розповісти,​ де ви вже шукали відповідь на ваше запитання. ("Я дивився в розділі 4 і розділі 5.2, але не зміг знайти щось, що сказало б мені чи можливо це") Це дозволить програмісту дізнатися,​ де люди очікують знайти відповідь,​ таким чином, він може зробити документацію більш зручною. ​
 +
 +==== "Show me." ====
 +
 +One of the very best ways you can report a bug is by showing it to the programmer. Stand them in front of your computer, fire up their software, and demonstrate the thing that goes wrong. Let them watch you start the machine, watch you run the software, watch how you interact with the software, and watch what the software does in response to your inputs. ​
 +
 +Вони знають цю програму як свої п'​ять пальців. Вони знають,​ яким частинам вони довіряють і яких частинах можуть бути дефекти. Вони інтуїтивно знають що шукати. На той час, як програма зробить щось очевидно помилкова,​ вони можуть вже помітити щось ледь вловиме неправильне і це може дати їм ключ до розгадки. Вони можуть зрозуміти все, що комп'​ютер робить протягом тестового запуску,​ і вони можуть витягнути з цього важливі для них частини. ​
 +
 +Цього може бути недостатньо. Вони можуть вирішити,​ що їм потрібно більше інформації і попросити вас показати їм те ж саме ще раз. Вони можуть попросити вас розповісти процедуру запуску так, що вони зможуть відтворити помилку для себе стільки разів, скільки хочуть. Вони можуть спробувати змінювати процедуру кілька разів, щоб побачити,​ чи виникає проблема тільки в одному випадку з сімейства пов'​язаних випадків. Якщо вам не пощастило,​ їм може знадобитися просидіти пару годин з набором інструментів розробника і почати по справжньому розбиратися. Але найбільш важливо - зробити так, щоб програміст подивився на комп'​ютер,​ коли він працює неправильно. Коли вони зможуть побачити що відбувається ні їхніх очах помилку,​ вони зможуть взяти її і спробувати виправити. ​
 +
 +==== "Show me how to show myself."​ ====
 +
 +This is the era of the Internet. This is the era of worldwide communication. This is the era in which I can send my software to somebody in Russia at the touch of a button, and he can send me comments about it just as easily. But if he has a problem with my program, he can't have me standing in front of it while it fails. "Show me" is good when you can, but often you can'​t. ​
 +
 +Якщо ви повинні повідомити про помилку програмістам,​ які не можуть персонально присутнім,​ мета вправи - ​​дати можливість їм відтворити проблему. Ви хочете,​ щоб програміст запустив власну копію програми,​ зробив ті ж речі, і зламав її таким же способом. Коли вони побачать,​ як виникає у них на очах, вони можуть мати з нею справу. ​
 +
 +Таким чином, скажіть їм точно, що ви робите. Якщо це графічна програма,​ розкажіть які кнопки і в якому порядку ви натискали. Якщо ви запускаєте програму,​ набираючи команду,​ покажіть їм точно, яку команду ви набрали. Там, де це можливо,​ приведіть дослівну запис діалогу,​ показуючи які команди ви набирали,​ і що комп'​ютер видав вам у відповідь. ​
 +
 +Дайте програмісту всі вхідні дані, про які ви можете подумати. Якщо програма читає файл, вам, імовірно,​ буде потрібно надіслати копію файлу. Якщо програма спілкується з іншим комп'​ютером по мережі,​ ви, ймовірно,​ не зможете надіслати копію цього комп'​ютера,​ але ви зможете,​ принаймні,​ сказати яка це різновид комп'​ютера,​ і (якщо можете) які програми на ньому запущені. ​
 +
 +==== "Works for me. So what goes wrong?"​ ====
 +
 +If you give the programmer a long list of inputs and actions, and they fire up their own copy of the program and nothing goes wrong, then you haven'​t given them enough information. Possibly the fault doesn'​t show up on every computer; your system and theirs may differ in some way. Possibly you have misunderstood what the program is supposed to do, and you are both looking at exactly the same display but you think it's wrong and they know it's right. ​
 +
 +Таким чином, також опишіть,​ що сталося. Опишіть точно, що ви побачили. Опишіть,​ чому ви думаєте,​ щось, що ви побачили неправильно;​ ще краще опишіть точно, що ви очікували побачити. Якщо ви говорите "і тоді вона зробила це неправильно",​ ви опускаєте важливу інформацію. ​
 +
 +Якщо ви побачили повідомлення про помилку,​ повідомте програмісту точно й акуратно,​ що це було за повідомлення. Це важливо! На цій стадії програмісти не намагаються виправити проблему:​ вони тільки намагаються виявити її. Їм треба знати, що пішло неправильно,​ і ці повідомлення про помилки - кращий спосіб розповісти про це. Запишіть повідомлення про помилки,​ якщо у вас немає більш легкого способу їх запам'​ятати,​ але не варто повідомляти про те, що програма видала повідомлення про помилку без опису того, що це було за повідомлення. ​
 +
 +Особливо якщо повідомлення про помилку містить в собі числа, дозвольте програмістам їх впізнати. Не вважайте,​ що в них немає сенсу тільки тому, що ви не можете його побачити. Числа містять всі види інформації,​ які можуть бути прочитані програмістами,​ і вони часто містять ключову інформацію. Числа містяться в повідомленнях тому, що комп'​ютер не може повідомити про помилку словами,​ але робить найкраще,​ що може зробити,​ щоб надати вам важливу інформацію. ​
 +
 +На цій стадії програмісти ефективно виконують роботу детектива. Вони не знають,​ що сталося,​ і вони не можуть самі підібратися досить близько,​ щоб побачити,​ як це відбувається,​ тому вони шукають докази,​ які це підкажуть. Повідомлення про помилки,​ малозрозумілі рядки чисел, і навіть незрозумілі затримки так само важливі як відбитки пальців на місці злочину. Тримайте їх! 
 +
 +If you are using Unix, the program may have produced a core dump. Core dumps are a particularly good source of clues, so don't throw them away. On the other hand, most programmers don't like to receive huge core files by e-mail without warning, so ask before mailing one to anybody. Also, be aware that the core file contains a record of the complete state of the program: any "​secrets"​ involved (maybe the program was handling a personal message, or dealing with confidential data) may be contained in the core file. 
 +
 +==== "So then I tried . . ." ====
 +
 +There are a lot of things you might do when an error or bug comes up. Many of them make the problem worse. A friend of mine at school deleted all her Word documents by mistake, and before calling in any expert help, she tried reinstalling Word, and then she tried running Defrag. Neither of these helped recover her files, and between them they scrambled her disk to the extent that no Undelete program in the world would have been able to recover anything. If she'd only left it alone, she might have had a chance. ​
 +
 +Користувачі на зразок цього схожі на мангуста загнаного в кут: впираючись спиною в стіну і дивлячись смерті в обличчя,​ він несамовито нападає,​ тому, що робити щось має бути краще, ніж нічого не робити. Це мало підходить до того типу проблем,​ які трапляються з комп'​ютером. ​
 +
 +Instead of being a mongoose, be an antelope. When an antelope is confronted with something unexpected or frightening,​ it freezes. It stays absolutely still and tries not to attract any attention, while it stops and thinks and works out the best thing to do. (If antelopes had a technical support line, it would be telephoning it at this point.) Then, once it has decided what the safest thing to do is, it does it. 
 +
 +When something goes wrong, immediately stop doing anything. Don't touch any buttons at all. Look at the screen and notice everything out of the ordinary, and remember it or write it down. Then perhaps start cautiously pressing "​OK"​ or "​Cancel",​ whichever seems safest. Try to develop a reflex reaction - if a computer does anything unexpected, freeze. ​
 +
 +If you manage to get out of the problem, whether by closing down the affected program or by rebooting the computer, a good thing to do is to try to make it happen again. Programmers like problems that they can reproduce more than once. Happy programmers fix bugs faster and more efficiently. ​
 +
 +==== "I think the tachyon modulation must be wrongly polarised."​ ====
 +
 +It isn't only non-programmers who produce bad bug reports. Some of the worst bug reports I've ever seen come from programmers,​ and even from good programmers. ​
 +
 +I worked with another programmer once, who kept finding bugs in his own code and trying to fix them. Every so often he'd hit a bug he couldn'​t solve, and he'd call me over to help. "​What'​s gone wrong?"​ I'd ask. He would reply by telling me his current opinion of what needed to be fixed. ​
 +
 +This worked fine when his current opinion was right. It meant he'd already done half the work and we were able to finish the job together. It was efficient and useful. ​
 +
 +But quite often he was wrong. We would work for some time trying to figure out why some particular part of the program was producing incorrect data, and eventually we would discover that it wasn'​t,​ that we'd been investigating a perfectly good piece of code for half an hour, and that the actual problem was somewhere else. 
 +
 +I'm sure he wouldn'​t do that to a doctor. "​Doctor,​ I need a prescription for Hydroyoyodyne."​ People know not to say that to a doctor: you describe the symptoms, the actual discomforts and aches and pains and rashes and fevers, and you let the doctor do the diagnosis of what the problem is and what to do about it. Otherwise the doctor dismisses you as a hypochondriac or crackpot, and quite rightly so. 
 +
 +It's the same with programmers. Providing your own diagnosis might be helpful sometimes, but always state the symptoms. The diagnosis is an optional extra, and not an alternative to giving the symptoms. Equally, sending a modification to the code to fix the problem is a useful addition to a bug report but not an adequate substitute for one. 
 +
 +If a programmer asks you for extra information,​ don't make it up! Somebody reported a bug to me once, and I asked him to try a command that I knew wouldn'​t work. The reason I asked him to try it was that I wanted to know which of two different error messages it would give. Knowing which error message came back would give a vital clue. But he didn't actually try it - he just mailed me back and said "No, that won't work". It took me some time to persuade him to try it for real. 
 +
 +Using your intelligence to help the programmer is fine. Even if your deductions are wrong, the programmer should be grateful that you at least tried to make their life easier. But report the symptoms as well, or you may well make their life much more difficult instead. ​
 +
 +==== "​That'​s funny, it did it a moment ago." ====
 +
 +Say "​intermittent fault" to any programmer and watch their face fall. The easy problems are the ones where performing a simple sequence of actions will cause the failure to occur. The programmer can then repeat those actions under closely observed test conditions and watch what happens in great detail. Too many problems simply don't work that way: there will be programs that fail once a week, or fail once in a blue moon, or never fail when you try them in front of the programmer but always fail when you have a deadline coming up. 
 +
 +Most intermittent faults are not truly intermittent. Most of them have some logic somewhere. Some might occur when the machine is running out of memory, some might occur when another program tries to modify a critical file at the wrong moment, and some might occur only in the first half of every hour! (I've actually seen one of these.) ​
 +
 +Also, if you can reproduce the bug but the programmer can't, it could very well be that their computer and your computer are different in some way and this difference is causing the problem. I had a program once whose window curled up into a little ball in the top left corner of the screen, and sat there and sulked. But it only did it on 800x600 screens; it was fine on my 1024x768 monitor. ​
 +
 +The programmer will want to know anything you can find out about the problem. Try it on another machine, perhaps. Try it twice or three times and see how often it fails. If it goes wrong when you're doing serious work but not when you're trying to demonstrate it, it might be long running times or large files that make it fall over. Try to remember as much detail as you can about what you were doing to it when it did fall over, and if you see any patterns, mention them. Anything you can provide has to be some help. Even if it's only probabilistic (such as "it tends to crash more often when Emacs is running"​),​ it might not provide direct clues to the cause of the problem, but it might help the programmer reproduce it. 
 +
 +Most importantly,​ the programmer will want to be sure of whether they'​re dealing with a true intermittent fault or a machine-specific fault. They will want to know lots of details about your computer, so they can work out how it differs from theirs. A lot of these details will depend on the particular program, but one thing you should definitely be ready to provide is version numbers. The version number of the program itself, and the version number of the operating system, and probably the version numbers of any other programs that are involved in the problem. ​
 +
 +==== "So I loaded the disk on to my Windows . . ." ====
 +
 +Writing clearly is essential in a bug report. If the programmer can't tell what you meant, you might as well not have said anything. ​
 +
 +I get bug reports from all around the world. Many of them are from non-native English speakers, and a lot of those apologise for their poor English. In general, the bug reports with apologies for their poor English are actually very clear and useful. All the most unclear reports come from native English speakers who assume that I will understand them even if they don't make any effort to be clear or precise. ​
 +
 +Be specific. If you can do the same thing two different ways, state which one you used. "I selected Load" might mean "I clicked on Load" or "I pressed Alt-L"​. Say which you did. Sometimes it matters. ​
 +Be verbose. Give more information rather than less. If you say too much, the programmer can ignore some of it. If you say too little, they have to come back and ask more questions. One bug report I received was a single sentence; every time I asked for more information,​ the reporter would reply with another single sentence. It took me several weeks to get a useful amount of information,​ because it turned up one short sentence at a time. 
 +Be careful of pronouns. Don't use words like "​it",​ or references like "the window",​ when it's unclear what they mean. Consider this: "I started FooApp. It put up a warning window. I tried to close it and it crashed."​ It isn't clear what the user tried to close. Did they try to close the warning window, or the whole of FooApp? It makes a difference. Instead, you could say "I started FooApp, which put up a warning window. I tried to close the warning window, and FooApp crashed."​ This is longer and more repetitive, but also clearer and less easy to misunderstand. ​
 +Read what you wrote. Read the report back to yourself, and see if you think it's clear. If you have listed a sequence of actions which should produce the failure, try following them yourself, to see if you missed a step. 
 +
 +==== Summary ====
 +
 +The first aim of a bug report is to let the programmer see the failure with their own eyes. If you can't be with them to make it fail in front of them, give them detailed instructions so that they can make it fail for themselves. ​
 +In case the first aim doesn'​t succeed, and the programmer can't see it failing themselves, the second aim of a bug report is to describe what went wrong. Describe everything in detail. State what you saw, and also state what you expected to see. Write down the error messages, especially if they have numbers in. 
 +When your computer does something unexpected, freeze. Do nothing until you're calm, and don't do anything that you think might be dangerous. ​
 +By all means try to diagnose the fault yourself if you think you can, but if you do, you should still report the symptoms as well. 
 +Be ready to provide extra information if the programmer needs it. If they didn't need it, they wouldn'​t be asking for it. They aren't being deliberately awkward. Have version numbers at your fingertips, because they will probably be needed. ​
 +Write clearly. Say what you mean, and make sure it can't be misinterpreted. ​
 +Above all, be precise. Programmers like precision. ​
 +
 +==== Here you can report bug ====
 +
 +[[http://​code.google.com/​p/​flylinkdc/​issues/​list|bug tracker]]
uk/bugreport.txt · В останнє змінено: 2012/11/08 22:15 (зовнішнє редагування)