Kaip parašyti gerą klaidos aprašymą (DI ar kūrėjui)

Geras klaidos aprašymas leidžia kitam žmogui ar DI pamatyti tą pačią problemą, kurią pamatėte jūs, nieko neklausdami. Jam reikia konkretaus pavadinimo, tikslių žingsnių problemai atkurti, to, ko tikėjotės, to, kas iš tikrųjų nutiko, bet kokio klaidos pranešimo nukopijuoto žodis į žodį ir to, kur tai įvyko: kuriame puslapyje, naršyklėje, įrenginyje ir su kuriuo naudotoju. Vienas klaidos aprašymas — viena klaida, su ekrano nuotrauka, jei tai padeda.

Dauguma klaidų suprasti trunka ilgiau nei ištaisyti. Aiškus aprašymas pašalina supratimo dalį. Tai dar svarbiau su DI įrankiais: DI negali užduoti patikslinančio klausimo apie tai, ką turėjote omenyje sakydami „atsiskaitymas keistas“, todėl spėja — o klaidingas spėjimas gali sugadinti ir kažką kita.

Šablonas

Nukopijuokite ir užpildykite:

Pavadinimas: [Kas negerai, kur] — pvz., „Rezervavimo forma atmeta laikus po 18 val.“

Žingsniai atkurti:
1. ...
2. ...
3. ...

Tikėtasi: [kas turėtų nutikti]
Faktiškai: [kas nutiko vietoj to]

Klaidos pranešimas: [tikslus tekstas, jei yra]
Kur: [puslapis/URL, naršyklė, įrenginys, prisijungta kaip kuris naudotojas]
Kaip dažnai: [kiekvieną kartą / kartais / vieną kartą]
Ekrano nuotrauka arba įrašas: [pridėta]

Likusi šio gido dalis paaiškina kiekvieną dalį.

1 žingsnis: pirmiausia atkurkite klaidą

Prieš rašydami pabandykite klaidą atkurti. Sužinosite, kurie žingsniai svarbūs ir ar ji pasikartoja kiekvieną kartą.

• Pradėkite nuo švaraus būsenos: atnaujinkite puslapį arba atsijunkite ir prisijunkite iš naujo.
• Užsirašykite kiekvieną paspaudimą ir kiekvieną įvestą dalyką.
• Raskite trumpiausią kelią, kuris sukelia klaidą.
• Pabandykite kitą naršyklę ar paskyrą. Jei tai vyksta tik vienam naudotojui, tai didelė užuomina.

Daugiau apie tai — kaip derinti DI sukurtą programėlę.

2 žingsnis: parašykite konkretų pavadinimą

Pavadinime turi būti aišku, kas negerai ir kur, kad žmogus, peržiūrintis sąrašą, žinotų, kuri tai klaida.

3 žingsnis: išvardykite tikslius žingsnius

Sunumeruokite juos. Būkite konkretūs: kuris puslapis, koks mygtukas, ką įvedėte.

1. Prisijunkite kaip klientas (testinė paskyra: customer@example.com).
2. Įdėkite „Starter kit“ į krepšelį.
3. Įveskite nuolaidos kodą WELCOME10 ir spustelėkite Apply.
4. Spustelėkite Checkout.

„Pabandykite atsiskaityti su kodu“ praleidžia detales, kurios dažnai svarbios: kuris naudotojas, koks produktas, koks kodas, ar jis buvo pritaikytas pirma.

4 žingsnis: numatytas ir faktinis rezultatas

Tai pagrindinė aprašymo dalis. Nurodykite abu, nes skirtumas ir yra klaida.

• Tikėtasi: atsidaro atsiskaitymo puslapis su rodoma 10 % nuolaida bendroje sumoje.
• Faktiškai: mygtukas sekundę rodo sukimosi indikatorių, o paskui nieko nevyksta. Be nuolaidos kodo atsiskaitymas veikia.

Be „tikėtasi“ skaitytojas gali nežinoti, kad elgesys neteisingas. Be „faktiškai“ jis nežino, ko ieškoti.

5 žingsnis: nukopijuokite klaidas tiksliai

Klaidų pranešimai yra greičiausias kelias į priežastį. Kopijuokite juos kaip tekstą, žodis į žodį — neparafrazuokite.

Kur juos rasti:

• Ekrane: bet kuris pranešimas, kurį rodo programėlė.
• Naršyklės konsolė: atidarykite kūrėjo įrankius (F12 arba dešiniu pelės mygtuku → Inspect) ir pažiūrėkite Console skirtuką, ar nėra raudonų eilučių.
• Network skirtukas: kūrėjo įrankiuose raskite nesėkmingą užklausą ir užsirašykite jos URL ir būsenos kodą (pavyzdžiui POST /api/checkout → 500).
• Serverio žurnalai, jei turite prieigą.

Eilutė, pavyzdžiui TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48, dažnai tiesiai nurodo problemą.

6 žingsnis: pridėkite kontekstą

• Kur: puslapio URL, aplinka (peržiūra, testinė ar gyva).
• Kas: kuris naudotojas ar vaidmuo — administratorius, narys, neprisijungęs.
• Įrenginys ir naršyklė: „Safari on iPhone“ ir „Chrome on Windows“ gali skirtis.
• Duomenys: bet kas neįprasto įraše — labai ilgas tekstas, specialieji simboliai, daug elementų.
• Kada prasidėjo: „po vakarykščio nuolaidos kodų pakeitimo“ — auksas.
• Kaip dažnai: kiekvieną kartą arba vieną kartą iš dešimties.

7 žingsnis: parodykite

Ekrano nuotrauka su apibraukta problema arba trumpas ekrano įrašas pašalina neaiškumus — ypač maketo klaidoms. Jei jūsų DI įrankis priima vaizdus, pridėkite vieną. Nukirpkite viską privataus, įskaitant raktus ir kitų žmonių duomenis.

Klaidų aprašymai DI kūrimo įrankiui

Ta pati struktūra veikia kaip užklausa. Du papildymai padeda:

• Pasakykite, ko nereikia keisti, kad pataisymas nesukeltų naujos problemos.
• Paprašykite patikrinti pataisymą, o ne tik ją parašyti.

Prisijungęs kaip klientas, su „Starter kit“ krepšelyje ir pritaikytu kodu WELCOME10, paspaudus Checkout nieko nevyksta. Tikėtasi: atsidaro atsiskaitymo puslapis su 10 % nuolaida bendrai sumai. Faktiškai: trumpas sukimosi indikatorius, o paskui nieko. Network skirtukas rodo, kad POST /api/checkout grąžino 500. Atsiskaitymas be kodo veikia. Raskite priežastį ir ištaisykite nekeisdami, kaip skaičiuojamos kainos užsakymams be kodo. Tada patikrinkite atsiskaitymą su procentiniu kodu, fiksuotos sumos kodu ir be kodo.

Jei nesate tikri dėl priežasties, pirma paprašykite diagnozės:

Kol kas nekeisk kodo. Remiantis šiuo aprašymu, kokios galimos priežastys ir kas patvirtintų kiekvieną iš jų?

Dažnos klaidos

• „Tai sugedo.“ Nėra žingsnių, nėra numatyto rezultato, nėra, pagal ką veikti.
• Kelios klaidos viename aprašyme. Kai kurios ištaisomos, kitos pamirštamos.
• Parafrazuotos klaidos. „Kažkoks undefined dalykas“ slepia naudingą dalį.
• Praleistas naudotojas ar vaidmuo. Daugelis klaidų paveikia tik administratorius arba tik naujus naudotojus.
• Aprašoma tik norimas pataisymas („pridėk null patikrinimą“), o ne problema.
• Paslapčių dalijimasis ekrano nuotraukose ar įklijuotuose žurnaluose.

Kontrolinis sąrašas

• Atkūriau klaidą ir radau trumpiausius žingsnius.
• Pavadinime aišku, kas negerai ir kur.
• Žingsniai sunumeruoti ir konkretūs.
• Nurodyti ir tikėtas, ir faktinis rezultatas.
• Klaidų pranešimai nukopijuoti tiksliai, su nesėkmingos užklausos URL ir būsenos kodu.
• Yra puslapis, aplinka, naudotojas, įrenginys ir naršyklė.
• Nurodžiau, kaip dažnai tai vyksta ir kada prasidėjo.
• Pridėta ekrano nuotrauka arba įrašas, pašalinus privačius duomenis.
• Vienas klaidos aprašymas — viena klaida.

Klaidų pranešimas Mythex agentui

Mythex projekte pats aprašymas yra užklausa. Kelios funkcijos padeda:

• Pridėkite ekrano nuotrauką peržiūros ar klaidos ekrano — iki 5 failų vienoje žinutėje.
• /fix nukreipia agentą į klaidos taisymą, o Plan režimas leidžia jam ištirti prieš redaguojant.
• /test priverčia agentą atkurti srautus pačioje peržiūroje ir praneša, ką mato.
• Revert to this point atšaukia pataisymą, kuris pablogino dalykus.

Dokumentacijos puslapis debugging with prompts naudoja tą pačią žingsnių / numatyto / faktinio struktūrą. Apie taisymo ir tikrinimo ciklą aplink tai žr. kaip kartoti iteracijas su DI sukurta programėle.

Klausimai