كيف تكتب تقرير خطأ يفهمه المطور من أول مرة
أغلب الأخطاء البرمجية ليست صعبة الإصلاح. الصعب هو رؤيتها، لأن التقرير الذي يصفها يغفل التفصيلة التي يحتاجها المطور بالضبط.
لماذا تفشل تقارير الأخطاء
التقرير المعتاد لقطة شاشة في محادثة وجملة مثل “صفحة الدفع لا تعمل”. من وجد الخطأ يعرف ما حدث تماما. أما المطور الذي يقرأ التقرير فلا يعرف.
فتبدأ الأسئلة. أي صفحة؟ أي متصفح؟ هل كنت مسجلا للدخول؟ ماذا ضغطت أولا؟ كل إجابة تأخذ وقتا، وحين تصل قد لا يتذكر المختبر التفاصيل.
الحل لا يعني جهدا أكبر من المطورين. الحل تقرير أفضل من المرة الأولى.
ما يحتاجه كل تقرير
يكون التقرير مفيدا حين يستطيع شخص آخر اتباعه ورؤية الخطأ نفسه. وهذا يحتاج هذه العناصر:
- عنوان واضح. اذكر ما تعطل وأين. “مجموع السلة يتجاهل كود الخصم في صفحة الدفع” أفضل من “مشكلة في السلة”.
- خطوات إعادة الخطأ. رقمها. وابدأ من نقطة معروفة، مثل رابط الصفحة أو تسجيل دخول جديد.
- النتيجة المتوقعة والنتيجة الفعلية. سطر لكل منهما. بهذا يعرف المطور شكل الإصلاح.
- البيئة. المتصفح وإصداره، ونظام التشغيل، وحجم الشاشة، والرابط الدقيق.
- الدليل. لقطة شاشة أو تسجيل قصير يظهر لحظة الخطأ.
إن أردت إضافة شيء واحد فقط إلى طريقة عملك الحالية، فأضف الخطوات. الخطأ الموثق بخطوات جيدة يجد طريقه إلى الإصلاح عادة. والخطأ بلا خطوات يبقى في قائمة الانتظار.
تفاصيل يسهل أن تفوتك
كثير من الأخطاء سببها أشياء لا يراها المختبر على الشاشة.
قد يبدو الزر معطلا، والسبب الحقيقي طلب فشل خلفه. وقد تعرض الصفحة بيانات قديمة لأن واجهة برمجية أعادت خطأ. وقد يتجمد النموذج لأن سكربتا توقف بسبب استثناء.
هذه الأدلة موجودة في أدوات المطور داخل المتصفح:
- سجلات الكونسول تعرض أخطاء السكربتات والتحذيرات.
- طلبات الشبكة تعرض الطلبات الفاشلة ورموز حالتها والوقت الذي استغرقته.
لا تحتاج أن تكون مطورا لتجمعها. افتح أدوات المطور قبل بدء الاختبار، وأبق تبويبي Console وNetwork مفتوحين، وانسخ كل ما يظهر باللون الأحمر إلى التقرير. سيقدر المطورون ذلك كثيرا.
اكتب خطوات يتبعها غيرك
الخطوات الجيدة قصيرة ومحددة. كل خطوة فعل واحد.
اكتب “اضغط زر الإضافة إلى السلة في أول منتج” بدلا من “أضف شيئا”. واكتب القيمة التي أدخلتها بدلا من “أدخل نصا”. وإن ظهر الخطأ مع بيانات معينة فقط، فاذكرها.
ثم اختبر خطواتك بنفسك. ابدأ من الخطوة الأولى واتبعها حرفيا. إن لم تستطع إعادة الخطأ من تقريرك، فلن يستطيع المطور أيضا.
وهذه عادات أخرى تساعد:
- خطأ واحد في كل تقرير. خطآن في تذكرة واحدة يبطئان الاثنين.
- اذكر عدد مرات ظهوره. في كل مرة، أو مرة من كل عشر محاولات، معلومة مفيدة.
- اذكر ما استبعدته مسبقا، مثل مسح الذاكرة المؤقتة أو تجربة متصفح آخر.
شارك التقرير حيث يجري العمل
التقرير الذي يبقى في محادثة يضيع. ضعه حيث يتابع فريقك المهام، مثل أداة تتبع المشكلات، وضع رابطه في المحادثة.
وفكر في من سيقرأ التقرير. مدير المنتج يحتاج عنوانا واضحا وملخصا قصيرا. والمطور يحتاج الخطوات والتفاصيل التقنية. التقرير الجيد يخدم الاثنين: الملخص في الأعلى والتفاصيل تحته.
وانتبه لما تشاركه خارج الفريق. قد تحتوي السجلات والطلبات على بيانات خاصة، فراجعها قبل إرسال التقرير إلى عميل أو مورد.
كيف يساعدك Stepix
جمع كل هذا يدويا يأخذ وقتا، ولهذا تتجاوزه تقارير كثيرة. ويتولى Stepix هذه المهمة عنك.
Stepix إضافة لمتصفح كروم. تلتقط لقطة شاشة أو تسجل فيديو حتى 5 دقائق، ويبني Stepix التقرير مع رابط الصفحة والبيئة وسجلات الكونسول وطلبات الشبكة. وحين تتتبع جلسة كاملة، يسجل كل نقرة كخطوة مرقمة مع لقطة شاشة.
يمكنك الرسم والكتابة على لقطة الشاشة قبل الحفظ. ويمكنك تحديد الحالة والخطورة والأولوية، وإرسال التقرير إلى GitHub أو GitLab أو Jira كمشكلة جديدة. وللمشاركة خارج أداة التتبع، أرسل رابط قراءة فقط واختر التفاصيل التقنية التي يراها المشاهد.
النصائح السابقة تنفع مع أي أداة. وStepix يجعلها الطريقة الافتراضية. تعرف على Stepix.
