این پست را قبلا در سایت لینوکس ریویو منتشر کرده بودم که به رحمت ایزدی پیوست. امید که اینجا ماندگارتر بماند. -متاسفانه منبع انگلیسی آن را پیدا نکردم.- منبع انگلیسی این مطلب به لطف دوست عزیزم نبی پیدا شد.
هر کسی که برنامه‌ای نوشته باشد به احتمال زیاد حداقل یک «گزارش باگ» دریافت می‌کند. گزارش‌هایی که اطلاعاتی نمی‌دهند «این کار نمی‌کند!»؛ گزارش‌هایی که بی‌معنی هستند؛ گزارش‌هایی که اطلاعات کافی نمی‌دهند؛ گزارش‌هایی که اطلاعات غلط می‌دهند؛ گزارش مشکلاتی که ناشی از خطاهای کاربرند؛ گزارش مشکلاتی که ناشی از اشکالات برنامه‌ی شخص دیگری است؛ گزارش مشکلاتی که ناشی از اشکالات شبکه است.
دلیل اینکه پشتیبانی فنی بدترین بخش برای کار کردن است همین گزارش باگ‌هاست. البته، همه‌ی گزارش باگ‌ها ناخوشایند نیستند: من در اوقات فراغت، نرم‌افزارهای free می‌نویسم و گاهی اوقات گزارش باگ‌هایی شفاف، مفید و حاوی اطلاعات کافی دریافت می‌کنم.
در این نوشتار سعی می‌کنم به طور شفاف یک گزارش باگ خوب را تشریح کنم. امیدوارم هر کسی قبل از نوشتن گزارش باگ این نوشته را بخواند.
به طور اساسی، هدف گزارش باگ این است که برنامهنویس عملکرد نادرست برنامه را جلوی خود ببیند. می‌توانید شخصاً باگ‌ها را به برنامه‌نویسان نشان دهید، یا دستورالعملی بنویسید که با دنبال کردن آن برنامه دچار اشکال شود. اگر برنامه دچار اشکال شود، برنامه‌نویسان اطلاعات بیشتری جمع آوری می‌کنند تا بفهمند که علت بروز اشکال در کجاست. اگر برنامه برای آن‌ها دچار اشکال نشود، از شما خواهند خواست تا اطلاعات بیشتری برای آن‌ها جمع آوری کنید.
در گزارش باگ‌ها سعی کنید حقایق را شفاف بیان کنید «من داشتم با کامپیوتر کار می‌کردم و این باگ اتفاق افتاد» و فرضیه‌هایتان را جدا از آن‌ها مطرح نمایید «من فکر می‌کنم مشکل از اینجا باشد». می‌توانید فرضیه‌ای ارائه نکنید ولی حقایق را از قلم نیاندازید.
وقتی باگی را گزارش می‌کنید، می‌خواهید که آن باگ برطرف (fix) شود. دلیلی بر فحش دادن به برنامهنویس یا لجبازی کردن نیست: ممکن است اشکال از طرف او باشد و این مشکل شماست، و ممکن است حق داشته باشید که از دست او عصبانی شوید، ولی باگ وقتی برطرف می‌شود که شما اطلاعات کافی و مورد نیاز را در اختیار برنامهنویس قرار دهید. به یاد داشته باشید که اگر برنامه‌ای free باشد، نویسنده آن را از روی لطف ارائه کرده است، پس اگر عده‌ی زیادی با او بد صحبت کنند و به او ناسزا بگویند ممکن است دیگر برنامه را ارائه نکند.
برای هوش برنامه‌نویستان کمی احترام قائل شوید: اگر برنامه ابداً کار نمی‌کرد، او احتمالا متوجه می‌شد. از آنجا که او متوجه نشده است پس حتماً برنامه برای او کار می‌کند. بنابراین، یا شما کاری متفاوت از آنچه که او انجام می‌دهد انجام می‌دهید، یا محیطی که شما در حال اجرای برنامه در آن هستید با محیط برنامهنویس فرق می‌کند. او به اطلاعات نیاز دارد؛ مقصود از گزارش باگ ارائه این اطلاعات است. ارائه اطلاعات بیشتر همیشه بهتر است.
بسیاری از برنامه‌ها، بخصوص برنامه‌های free لیست باگ‌های گزارش شده را منتشر می‌کنند. اگر لیستی از باگ‌های گزارش شده در دسترس شماست، ارزشمند است که پیش از گزارش باگ، آن‌ها را بخوانید تا متوجه شوید که قبلاً کسی آن را گزارش کرده یا خیر. اگر قبلاً باگ گزارش شده است، گزارش دوبار‌ه‌ی آن کار بیهوده‌ای است. ولی اگر فکر می‌کنید که اطلاعات بیشتری نسبت به آنچه گزارش شده دارید، می‌توانید برنامهنویس را از این موضوع مطلع کنید. برنامهنویس با داشتن اطلاعات بیشتر راحت‌تر می‌تواند باگ را برطرف کند.
این نوشتار پر از راهنمایی است. هیچ یک از این راهنمایی‌ها یک قانون مطلق نیستند. برنامه‌نویسان خاص، راه‌های خاصی برای دریافت گزارش باگ دارند. اگر برنامه با «اصول گزارش باگ» ارائه شده، آن را بخوانید. اگر مفاد آن سند با راهنمایی‌های ارائه شده در این نوشتار همخوانی ندارد، آن مفاد را دنبال کنید!
اگر باگی گزارش نمی‌کنید و تنها در استفاده از برنامه به کمک احتیاج دارید، باید اعلام کنید که قبلاً در کجا به دنبال پاسخ سؤالتان گشته‌اید. («من بخش ۵.۲ و فصل ۴ مستندات نرم‌افزار را خوانده‌ام ولی هیچ صحبتی از امکان‌پذیر بودن این قابلیت ذکر نشده») این به برنامه‌نویسان می‌گوید که مردم در کدام قسمت‌های مستندات به دنبال جوابشان می‌گردند، به این ترتیب آن‌ها مستندات را به نحوی اصلاح می‌کنند که استفاده از آن آسانتر باشد.
یکی از بهترین روش‌های گزارش باگ نشان دادن آن به برنامهنویس است. او را به جلوی کامپیوتر بیاورید، نرم‌افزار را اجرا کنید و توضیح دهید چه موقع برنامه درست کار نمی‌کند. اجازه دهید ببیند که کامپیوتر را روشن می‌کنید، ببیند نرم‌افزار را اجرا می‌کنید، ببیند با نرم‌افزار کار می‌کنید و ببیند که نرم‌افزار به ورودی شما چه پاسخی می‌دهد.
برنامهنویس برنامه را مثل کف دستش می‌شناسد. می‌داند به کدام بخش اطمینان دارد و کدام بخش ممکن است مسأله‌ساز شود. برنامهنویس می‌داند که به چه چیزی باید نگاه کند. مواقعی که برنامه عملیاتی کاملاً اشتباه انجام می‌دهد، ممکن است از روی رفتار قبلی برنامه متوجه اشکال برنامه شود. برنامهنویس می‌تواند در زمان اجرای تست برنامه کاملاً سیستم را تحت نظر بگیرد و نکات مهم را یادداشت کند.
این ممکن است کافی نباشد. ممکن است به این نتیجه برسد که به اطلاعات بیشتری نیاز دارد و از شما بخواهد که مجدداً اشکال برنامه را به او نشان دهید. ممکن است از شما بخواهد که در حین فرآیند تولید باگ با او صبحت کنید تا بتواند باگ را روی سیستم خودش هم ببیند. ممکن است تلاش کند فرآیند تولید باگ را چند بار تغییر دهد تا متوجه شود که برنامه فقط در آن فرآیند با اشکال روبه‌رو می‌شود یا در یک سلسله فرآیند دچار اشکال می‌شود. اگر بدشانس باشید، ممکن است نیاز باشد چندین ساعت با یک سری ابزارهای برنامه‌نویسی برنامه را تحلیل کنند تا علت مشخص شود. ولی مهم‌ترین بخش این است که برنامهنویس وقتی برنامه دچار اشکال می‌شود به کامپیوتر نگاه کند. وقتی متوجه اشکال شود، معمولاً آن گزارش باگ را متوجه می‌شود و سعی می‌کند که آن را برطرف کنند.
در عصر اینترنت هستیم. عصر ارتباطات جهانی. می‌توانم برنامه‌ام را برای شخصی در روسیه بفرستم و او دیدگاهش را در مورد آن ظرف چند دقیقه بگوید. ولی اگر برنامه اشکالی داشته باشد، او نمی‌تواند من را کنار کامپیوترش ببرد و اشکال را به من نشان دهد. «به من نشان بده» خوب است ولی اغلب امکان‌پذیر نیست.
اگر باید باگی را به برنامه‌نویسی که شخصاً حضور ندارد، گزارش بدهید، هدف شما باید فراهم کردن امکان «تولید مجدد باگ» باشد. از برنامهنویس بخواهید نسخه‌ای از برنامه که در اختیار شماست اجرا کند، همان اعمالی که شما انجام می‌دهید تکرار کند و همانطور که شما با اشکال روبه‌رو می‌شوید، با اشکال مواجه شود. وقتی که برنامهنویس با چشمان خود می‌بیند که اشکال بروز می‌کند، می‌تواند آن را برطرف کند.
پس دقیقاً به او بگویید چه کار کردید. اگر یک برنامه‌ی گرافیکی است، بگویید که روی کدام دکمه‌ها و به چه ترتیبی کلیک کردید. اگر یک برنامه‌ی تحت خط فرمان است، به طور دقیق به او بگویید چه چیزی تایپ کرده‌اید. در صورت امکان، باید کلمه به کلمه آنچه که در فرآیند تولید باگ اتفاق می‌افتد بگویید، نشان دهید چه دستوراتی نوشته‌اید و کامپیوتر به آن‌ها چه پاسخی داده است.
به برنامهنویس تمام ورودی‌هایی که تصور می‌کنید ممکن است نقشی داشته باشند ارائه کنید. اگر برنامه اطلاعاتی از یک فایل می‌گیرد، یک کپی از آن فایل ارائه کنید. اگر از پایگاه داده استفاده می‌کند، یک خروجی مناسب از اطلاعات پایگاه داده بگیرید و ارائه کنید. اگر برنامه با کامپیوتر دیگری روی شبکه ارتباط پیدا می‌کند، احتمالاً نمی‌توانید یک کپی از آن کامپیوتر بفرستید، ولی حداقل می‌توانید نوع و مدل آن و نرم افزاری که بر روی آن نصب شده را ذکر کنید.
اگر به برنامهنویس لیستی طولانی از ورودی‌های برنامه و کارهایی که باید انجام شود دادید، نسخه‌ی خودش را اجرا کرد ولی برنامه به درستی کار کرد، به این معناست که شما اطلاعات کافی ارائه نکرده‌اید. احتمالاً اشکال روی هر کامپیوتری ظاهر نمی‌شود؛ کامپیوتر شما با کامپیوتر برنامهنویس به نوعی تفاوت دارد. احتمال دارد که شما در مورد عملکرد برنامه دچار سوءتفاهم شده باشید و نتیجه‌ای که شما مشاهده می‌کنید و فکر می‌کنید که اشتباه است همانی است که برنامهنویس می‌بیند و فکر می‌کند که صحیح است.
پس توضیح دهید که چه اتفاقی می‌افتد. به برنامهنویس بگویید که چه می‌بینید و فکر می‌کنید که چه چیزی اشتباه است؛ و حتی بهتر است بگویید انتظار دارید چه چیزی ببینید. اگر بگویید «…و بعد درست کار نکرد» اطلاعات مهمی را حذف کرده‌اید.
اگر پیام خطایی می‌بینید آن را شفاف و دقیق به برنامهنویس بگویید. پیام‌های خطا مهم هستند! در این مرحله برنامهنویس سعی نمی‌کند مشکل را حل کند، سعی می‌کند که آن را بیابد. او باید بداند که چه اشکالی بوجود آمده و پیام‌های خطا بهترین تلاش کامپیوتر برای بیان این موضوع هستند. اگر راه بهتری برای نگه‌داشتن پیام‌های خطا ندارید، آن‌ها را روی کاغذی یادداشت کنید. گزارش اینکه برنامه پیام خطایی می‌دهد بدون نوشتن آن پیام خطا بی‌ارزش است.
بخصوص وقتی در پیام خطا عددی وجود دارد، اجازه دهید برنامهنویس آن عدد را در اختیار داشته باشد. اینکه شما مفهوم آن اعداد را نمی‌فهمید دلیل بر بی‌اهمیت بودن آن پیام خطا نیست. اعداد زبانی دارند که برنامهنویس می‌تواند آن را متوجه شود و احتمالاً سرنخی برای یافتن علت بروز اشکال هستند. وقتی اعداد نمایش داده می‌شوند یعنی کامپیوتر آنقدر گیج شده که نمی‌تواند اشکال را در قالب کلمات بیان کند، با نمایش آن اعداد کامپیوتر اطلاعات با ارزشی ارائه می‌کند.
در این مرحله، برنامهنویس کاملاً نقش یک کارآگاه را بازی می‌کند. برنامهنویس نمی‌داند چه چیزی اتفاق افتاده و نمی‌تواند از نزدیک آن را تجربه کند، پس باید به دنبال سرنخی باشد که به منشاء مشکل برسد. پیام‌های خطا، اعداد بی‌معنی و حتی تأخیر غیر موجه برنامه مثل اثر انگشتی در صحنه‌ی جرم با‌ارزش هستند.
اگر از یونیکس استفاده می‌کنید، ممکن است برنامه core dump تولید کرده باشد. Core dumpها منبع خوبی از اطلاعات هستند پس آن‌ها را دور نیاندازید. از طرف دیگر، اغلب برنامه‌نویسان از گرفتن فایل‌های core بزرگ از طریق ایمیل خوشحال نمی‌شوند. پس پیش از ارسال، حتماً از برنامهنویس بپرسید. همچنین آگاه باشید که فایل core حاوی رکوردی از همه‌ی اطلاعات برنامه است: رمز‌های عبور (ممکن است برنامه اطلاعات خصوصی کاربر را نگه‌دارد یا به اطلاعات محرمانه‌ای دسترسی پیدا کند) هم در آن وجود دارد.
بعد از ظاهر شدن یک پیام خطا یا یک باگ کارهای زیادی می‌توان انجام داد. ولی بیشتر آن‌ها مشکل را بدتر می‌کنند. یکی از دوستان من همه‌ی فایل‌های word کامپیوترش را تصادفاً پاک کرد، بعد از آن به جای مشورت با یک متخصص، word را دوباره نصب کرد و بعد از آن Defrag را اجرا کرد. هیچکدام از آن‌ها به بازیابی فایل‌های پاک شده‌اش کمک نکردند و در واقع آن اعمال سیستمش را به وضعیتی کشاندند که هیچ برنامه‌ی Undelete ای در دنیا نتواند آن فایل‌ها را برگرداند. اگر او سیستمش را در همان وضعیت رها کرده بود، احتمالاً شانسی برای برگرداندن فایل‌هایش داشت.
چنین کاربرانی مثل میمون پوزه‌درازی هستند که یک گوشه‌گیر افتاده باشد: وقتی پشت به دیوار باشد و مرگ را در برابرش ببیند دیوانه‌وار حمله می‌کند چون کاری کردن بهتر از هیچ کاری نکردن است! چنین رفتاری با مشکلات کامپیوتری چندان سازگار نیست.
به جای میمون پوزه‌دراز بودن، بز کوهی باشید! وقتی بز کوهی با چیزی غیر منتظره یا ترسناک مواجه می‌شود، خشکش می‌زند. همانطور ثابت می‌ماند و سعی می‌کند جلب توجه نکند، موقعی که خشکش زده فکر می‌کند که بهترین کار برای خروج از این وضعیت چیست (اگر بزهای کوهی شماره تماس پشتیبانی فنی داشتند، احتمالاً در چنین وضعیتی با آنجا تماس می‌گرفتند) و پس از بررسی احتمالات، ایمن‌ترین راه ممکن را انتخاب می‌کنند.
وقتی اتفاق بدی می‌افتد، فوراً کار را متوقف کنید. هیچ دکمه‌ای را کلیک نکنید. به صفحه نگاه کنید و هر چیز غیرعادی که اتفاق افتاد یادداشت کنید. سپس با احتیاط دکمه‌ی ok یا cancel را بزنید (هرکدام که ایمن‌تر است) سعی کنید عکس‌العمل مناسبی نشان دهید – خشکتان بزند!
اگر تصمیم گرفتید از وضعیت بروز مشکل خارج شوید، با بستن برنامه یا با ریست کردن کامپیوتر، ایده‌ی خوبی است که سعی کنید دوباره آن اشکال را بوجود بیاورید. برنامه‌نویسان اشکالاتی که چند بار قابل تولید شدن هستند دوست دارند. فراموش نکنید که یک برنامهنویس خوشحال باگ‌ها را سریع‌تر و بهتر برطرف می‌کند.
«فکر می‌کنم ماجول tachyon اشتباهاً پولاریزه شده»
فقط غیر-برنامه‌نویسان نیستند که بد گزارش باگ می‌نویسند. بعضی از بدترین گزارش باگ‌هایی که در عمرم دیدم از برنامه‌نویسان بود و حتی از برنامه‌نویسان خوب.
مدتی با برنامهنویس دیگری کار می‌کردم که در کدهای خودش باگ‌هایی پیدا می‌کرد و سعی می‌کرد آن‌ها را برطرف کند. هر از گاهی به باگی برمی‌خورد که نمی‌توانست آن را برطرف کند، پس با من تماس می‌گرفت. من می‌پرسیدم «چه اشکالی بوجود آمده؟» و او چیزی که فکر می‌کرد باید اصلاح شود به من می‌گفت.
وقتی ایده‌ش درست بود خیلی خوب بود. یعنی او قبلاً نیمی از کار را انجام داده و ما می‌توانستیم با هم کار را تمام کنیم. این خیلی مفید و مؤثر بود.
ولی اغلب او اشتباه می‌کرد. مدتی کار می‌کردیم تا بفهمیم چرا یک بخش از برنامه داده‌ی غلط تولید می‌کند و بعد از نیم ساعت گشتن، ناگهان می‌فهمیدیم که آن بخش درست کار می‌کند و بخش دیگری مقصر است.
مطمئنم او این کار را با یک دکتر نمی‌کند. «دکتر من یه نسخه برای تب کریمه کنگو می‌خوام» مردم می‌دانند که نباید چنین چیزی را به یک دکتر بگویند: شما علایم را تشریح می‌کنید، ناراحتی، درد، تورم یا سرگیجه و اجازه می‌دهید دکتر مشکل را پیدا کند و برای رفع آن دارو تجویز کند. در غیر اینصورت دکتر شما را مالیخولیایی تشخیص می‌دهد.
در مورد برنامه‌نویسان هم همینطور است. ارائه‌ی تشخیصتان ممکن است گاهی مفید باشد، ولی همیشه علایم بروز اشکال را ذکر کنید. تشخیص علت بروز اشکال یک آیتم اضافی است نه یک جایگزین برای علایم بروز اشکال. همچنین، ارسال قسمتی از کد که تغییر داده شده و مشکل را برطرف می‌کند گزینه‌ی خوبی برای اضافه کردن است ولی معادل ذکر شرایط بروز باگ نیست.
اگر برنامهنویس از شما اطلاعات بیشتری خواست، آن را از خودتان نسازید! شخصی باگی را گزارش کرده بود، من از او خواستم تا دستوری را وارد کند که می‌دانستم کار نخواهد کرد. دلیل اینکه از او خواستم تا آن را وارد کند این بود که می‌خواستم بفهمم کدام پیام خطا را تولید می‌کند و از روی آن پیام خطا ریشه مشکل را بیابم. ولی او آن دستور را وارد نکرد – فقط به من ایمیل زد و گفت «نه، این دستور کار نخواهد کرد». مدتی زمان برد تا او را قانع کردم که آن دستور را بزند.
استفاده از هوشتان برای کمک به برنامهنویس خوب است. ولی حتی اگر عملتان اشتباه باشد، آن را انجام دهید. برنامهنویس از اینکه سعی کرده‌اید زندگیش را آسانتر کنید، سپاسگزار خواهد بود. ولی علایم را هم گزارش کنید، در غیر اینصورت زندگیش را بسیار سخت‌تر خواهید کرد.
به هر برنامه‌نویسی بروز «مشکل تناوبی» را بگویید چهره در هم می‌کشد. آسانترین مسائل آن‌هایی هستند که با یک مرحله اجرای فرآیند مشکلشان بروز می‌کند. برنامهنویس می‌تواند این فرآیند را در شرایط آزمایشی بررسی کند و ببیند چه اتفاقی می‌افتد. بسیاری از مسائل به این شکل نیستند: برنامه‌هایی هستند که هفته‌ای یکبار دچار اشکال می‌شوند، یا ماهی یکبار، یا وقتی سعی کنید به برنامهنویس نشانشان دهید دچار اشکال نمی‌شوند ولی وقتی موعد تحویل کار نزدیک است همیشه دچار اشکال می‌شوند.
بیشتر مشکلات تناوبی واقعاً متناوب نیستند. بیشتر آن‌ها منطقی دارند. بعضی از این مشکلات وقتی اتفاق می‌افتند که حافظه کم بیاید، بعضی وقتی پیش میایند که برنامه‌ی دیگری سعی کند فایلی را در زمان نامناسبی تغییر دهد و بعضی دیگر فقط نیم ساعت اول هر ساعت! (من خودم یکی از این باگ‌ها را دیده‌ام)
همچنین اینکه شما می‌توانید باگی را تولید کنید که برنامهنویس نمی‌تواند آن را تولید کند به تفاوت کامپیوترهای شما برمی‌گردد. برنامه‌ای داشتم که پنجره‌اش در قسمت بالا سمت چپ پیچ می‌خورد و دچار اشکال می‌شد ولی این اشکال فقط بر روی صفحه نمایش‌های با رزولوشن ۸۰۰×۶۰۰ اتفاق می‌افتاد و با رزولوشن ۱۰۲۴×۷۶۸ بدون اشکال ظاهر می‌شد.
برنامهنویس می‌خواهد هر اطلاعاتی که شما در مورد مسأله می‌توانید بدست آورید بداند. شاید بخواهد آن را روی ماشین دیگری امتحان کنید. آن را دو یا سه بار امتحان کنید و ببینید چند بار اشکال ظاهر می‌شود. اگر وقتی مشغول کار جدی هستید اشکال بروز می‌کند و وقتی می‌خواهید آن را توضیح دهید ظاهر نمی‌شود، احتمالاً اجرا برای طولانی مدت یا فایل‌های باز زیاد عامل بروز اشکال است.سعی کنید تا جایی که می‌توانید جزییات شرایط بروز اشکال را به خاطر بسپارید. اگر الگویی بین عوامل بروز اشکال می‌بینید آن را ذکر کنید. هر چیزی می‌تواند کمک کند. حتی اگر به نظر بی‌ارتباط باشد (مثلاً «به نظر می‌رسد وقتی Emacs در حال اجرا باشد برنامه بیشتر دچار اشکال می‌شود»)، چنین جزییاتی ممکن است سرنخ مستقیمی به علت بروز مشکل نباشد ولی به برنامهنویس کمک می‌کند که اشکال را دوباره تولید کند.
مهمتر از همه، اغلب اوقات برنامهنویس می‌خواهد مطمئن شود که با یک مسأله تناوبی واقعی روبروست یا یک اشکال مربوط به کامپیوتر. برنامهنویس اطلاعات زیادی از کامپیوتر شما می‌خواهد تا بداند که چقدر با کامپیوتر او متفاوت است. بسیاری از این جزییات به ماهیت برنامه ربط دارند ولی چیزی که قطعاً برای ارائه‌ی آن باید آماده باشید نسخه‌ی برنامه‌هایی است که استفاده می‌کنید. نسخه‌ی خود برنامه و نسخه‌ی سیستم عامل و احتمالاً نسخه‌ی برنامه‌هایی که با برنامه درگیر هستند.
شفاف نوشتن در گزارش باگ ضروری است. اگر برنامهنویس نفهمد که شما چه می‌گویید، احتمالاً مثل این است که شما اصلا چیزی نگفته‌اید.
من از همه‌ی نقاط دنیا گزارش باگ دریافت می‌کنم. بسیاری از آن‌ها غیر انگلیسی زبان هستند و بسیاری از آن‌ها به خاطر ضعیف بودن انگلیسی‌شان عذرخواهی می‌کنند. عموما، عذرخواهی در گزارش باگ‌هایی است که مفید و شفاف هستند. اغلب گزارش‌های غیرشفاف از انگلیسی زبانان است که تصور می‌کنند من زبانشان را می‌فهمم، این‌ها حتی تلاشی برای شفاف کردن یا دقیق‌تر بیان کردن منظورشان انجام نمی‌دهند.
دقیق باشید. اگر فرآیندی به دو طریق قابل انجام است بیان کنید که از کدام روش آن را انجام دادید. «من بارگذاری کردم» می‌تواند «روی دکمه‌ی بارگذاری کلیک کردم» یا «من کلید‌های ALT+L را زدم» تصور شود. پس بگویید کدامیک را انجام داده‌اید. گاه این موضوع اهمیت دارد.
مفصل بگویید. اطلاعات بیشتری بدهید. اگر زیاد بنویسید برنامهنویس می‌تواند بخشی از آن را نادیده بگیرد. اگر کم بگویید، برنامهنویس باید بیاید و سؤال‌های بیشتری بپرسد. گزارش باگی دریافت کردم که یک خط بود؛ هر موقع اطلاعات بیشتری می‌خواستم، گزارش دهنده یک جمله‌ی دیگر جواب می‌داد. چند هفته طول کشید تا به اطلاعات کافی رسیدم به این دلیل که هر بار گزارش دهنده فقط یک جمله تایپ می‌کرد.
مواظب ضمیر‌ها باشید. از کلماتی مثل «آن» یا عبارات معرفه «همان پنجره» وقتی که باعث ابهام می‌شوند، استفاده نکنید. این را ببینید: «من برنامه‌ی FooApp رو اجرا کردم. اون یه پیام هشدار داد. سعی کردم که ببندمش و کرش کرد.» در اینجا شفاف نیست که کاربر سعی کرده کدام پنجره را ببندد. سعی کرده پنجره‌ی هشدار را ببندد یا کل برنامه را؟ به جای آن می‌توانید بگویید «من برنامه‌ی FooApp را اجرا کردم، که یک پیام هشدار داد. سعی کردم پنجره‌ی هشدار را ببندم که برنامه‌ی FooApp کرش کرد» این گزارش باگ طولانی‌تر است ولی شفاف‌تر بوده و درک آن آسانتر است.
آنچه نوشته‌اید بخوانید. گزارش باگ را برای خودتان بخوانید و ببینید که از نظر خودتان شفاف است. اگر لیست اعمالی که باعث بروز باگ می‌شوند نوشته‌اید، خودتان یکبار آن‌ها را دنبال کنید و ببینید که چیزی را از قلم نیانداخته باشید.
مقصود از گزارش باگ نشان دادن اشکال برنامه به برنامهنویس است. اگر نمی‌توانید اشکال را به برنامهنویس نشان دهید، دستورالعملی بنویسید که با پیروی از آن برنامه دچار اشکال می‌شود.
در صورتی‌‌که گام اول موفقیت آمیز نبود، و برنامهنویس نتوانست اشکال را ببیند، هدف دوم تشریح حالت بروز اشکال است. همه چیز را با جزییات توضیح دهید. بگویید چه چیزی می‌بینید و انتظار دارید چه چیزی ببینید. پیام‌های خطا را یادداشت کنید، بخصوص پیام‌هایی که عدد در آن‌ها وجود دارد.
وقتی کامپیوتر رفتاری غیر منتظره نشان می‌دهد، تکان نخورید. به هیچ چیز دست نزنید تا وقتی که آرام شوید. کاری که حدس می‌زنید خطرناک است انجام ندهید.
اگر می‌توانید، با هر ابزاری سعی کنید ریشه مشکل را پیدا کنید، ولی اگر ریشه مشکل را یافتید، همچنان باید علایم بروز اشکال را در گزارشتان بنویسید.
در صورت درخواست برنامهنویس، برای ارائه‌ی اطلاعات بیشتر حاضر باشید. اگر به اطلاعاتی نیاز نداشته باشد آن را از شما نمی‌خواهد. برنامهنویس سر به هوا نیست. نسخه‌ی برنامه‌ها را در دسترس داشته باشید چون به احتمال زیاد نیاز خواهند شد.
شفاف بنویسید. بگویید که منظورتان چیست و مطمئن شوید که از آن برداشت دیگری نمی‌شود.
از همه مهمتر، دقیق باشید. برنامه‌نویسان دقت را دوست دارند.
……………………………………………………………………………………………………
پانویس:
- گزارش باگ، پیامی است که حاوی درست کار نکردن برنامه در یک یا چند قسمت است.
- ترک دعوا: من خودم هیچ وقت میمون پوزه‌دراز یا بز کوهی ندیدم. شاید جانورشناسی من درست نباشد.
