{"id":597,"date":"2012-10-10T12:03:32","date_gmt":"2012-10-10T10:03:32","guid":{"rendered":"http:\/\/borkedcode.com\/wp\/?p=597"},"modified":"2012-10-10T12:03:32","modified_gmt":"2012-10-10T10:03:32","slug":"what-are-the-qualities-of-a-good-bug-entry","status":"publish","type":"post","link":"https:\/\/www.borkedcode.com\/wp2\/2012\/10\/10\/what-are-the-qualities-of-a-good-bug-entry\/","title":{"rendered":"What Are the Qualities of a Good Bug Entry?"},"content":{"rendered":"

Making a bug report can be a surprisingly subtle process \u2013 and precision is everyone\u2019s friend when it comes to bugs.\u00a0 In this section, we\u2019ll briefly address the most important aspects of bug reporting.\u00a0 Always remember:\u00a0 the goal of a bug report is to get a problem fixed<\/em>.<\/p>\n

The process of removing problems and fixing bugs in software (or hardware, for that matter) is a lot like the process of identifying an illness in medicine:<\/p>\n

    \n
  1. Study the symptoms<\/li>\n
  2. Trace the symptoms to a root cause<\/li>\n
  3. Once the root cause is found, cure the root cause, or<\/li>\n
  4. If the root cause is not treatable, find a treatment that eases or removes the symptoms<\/li>\n<\/ol>\n

    In the case of software, the identification of the root cause is generally the process of locating a specific set of instructions that either conflicts with another set, or that itself is mal-formed.\u00a0 The symptoms experienced are generally signposts that point towards this set of instructions, and taking those symptoms and turning it into a map of the problem is how the developer finds the bug in question.<\/p>\n

    With that said, the bug report <\/em><\/strong>is the primary tool you have in helping developers identify bugs in software you\u2019ve used.\u00a0 There are bad bug reports (\u201cIt\u2019s broken.\u201d \u2013 that\u2019s not a joke, this author has seen bug reports that read exactly that way), and good ones.\u00a0 What are the qualities of a good one?<\/p>\n

    Concise<\/h3>\n

    A good bug report is concise<\/em> \u2013 it is to the point, and spends a minimum of time talking around the problem.\u00a0 Use clear language, and only enough to describe the issue at hand.<\/p>\n

    Isolated<\/h3>\n

    Isolation is making sure that any individual bug report refers to only a single bug.\u00a0 When entering a bug report, always try to make one report per bug, and one bug per report.\u00a0 When chasing a problem, a developer will have a much easier time locating and repairing a single error \u2013 not because he or she can\u2019t deal with more than one thing at a time, but because it\u2019s very likely that any given set of bugs probably exist in different sections of code, or even different files or directories.\u00a0 If a developer had to look at two different bugs at once, it\u2019s likely that the two would confuse each others\u2019 trails, making it very hard for the developer to dig out either one.<\/p>\n

    For example, if a \u201cFile \u2013 Open\u201d dialog throws an error message, that is a different bug than attempting to navigate to a new page and having another error message \u2013 even if the messages end up saying the same thing.\u00a0 These two occurrences are better off being entered into two separate bug reports.<\/p>\n

    Although multiple reports of the same bug can also be a problem (because the QA staff must verify a bug, and multiple reports potentially use up their time), if you are in doubt as to whether what you are looking at is new or a duplicate, it is better to enter it as a new bug.\u00a0 If it is later identified as a duplicate, the entry will be closed, but a link will be made in it indicating the bug report that originally identified the problem.<\/p>\n

    Specific<\/h3>\n

    Specificity is crucial to the technicians trying to find the source of the problem.\u00a0 This is related to isolation (in that your report should pinpoint a single issue), but is also its own subject \u2013 when you describe the bug, be as specific as possible.\u00a0 For example, if you experience an error when you navigate to a particular screen of an application or website, what is the method by which you navigate to it?\u00a0 Are you clicking a link from another page, or picking an item from a menu?\u00a0 Are you pressing a \u201csubmit\u201d button and being redirected there?\u00a0 Are you using a Mac or a PC?\u00a0 Knowing these details can chop minutes or hours off of the process of finding the source of the problem.<\/p>\n

    Reproducible<\/h3>\n

    The first thing a QA tester or developer will tell you when asked what makes a good bug entry is this:<\/p>\n

    Steps to Replicate<\/em>.<\/p>\n

    Although often a bug does not evidence reliable behavior, if the reporter can find a method by which they can reproduce the problem consistently, that is vitally important information.\u00a0 Including that in a bug report can mean the difference between saying \u201cOh, I see, click!\u201d and spending hours or days in detective work trying to find the error and observe what it is doing.<\/p>\n

    Steps can be laid out in simple numbered lines, and often this is the best method.\u00a0 For example:<\/p>\n

      \n
    1. Open [application or site]<\/li>\n
    2. Open menu X with Alt+X keypress<\/li>\n
    3. Click on menu item \u201cwidget\u201d with mouse<\/li>\n
    4. When \u201cwidget\u201d page\/screen is loading, click on banner in upper left<\/li>\n
    5. Computer will ignite and spark (describe problem behavior here)<\/li>\n<\/ol>\n

      Prioritized<\/h3>\n

      If possible, a scale of importance should be applied to the bug. \u00a0Having a priority assigned to a bug helps the development team determine which bugs should be addressed first, and which might not be so important to deal with.\u00a0 Not every bug should be considered a \u201cstop the presses!\u201d matter, just as not every bug can be written off as trivial.<\/p>\n

      This topic brings into spotlight the nature of individual perspective.\u00a0 When dealing with software and web development, at least two widely differing perspectives are brought together to work towards a common goal.\u00a0 Those differing perspectives are the most common causes of friction and strife in teams.<\/p>\n

      For example, the perspectives of a developer are very different from those of a marketing professional, because the two measure value based on very different elements.\u00a0 A developer can look at a spelling error on a label and consider it the most trivial of issues, because generally software professionals measure importance as directly proportional to the complexity of a problem \u2013 changing the text on a label to correct its spelling is among the simplest operations one can perform.\u00a0 Meanwhile, the aforementioned marketing professional measures importance by the content and impact of memes (ideas and concepts) \u2013 for that person, a spelling error in a highly-visible place will be considered a critical and business-threatening problem.<\/p>\n

      With this in mind, when creating a bug report, the reporter should assign to the bug a level of importance that the reporter feels is appropriate.\u00a0 This will place the bug in the queue for resolution at an appropriate level for its importance.\u00a0 Don\u2019t worry overmuch about being precisely correct \u2013 if some question exists about the importance of a bug, the development staff will return to the reporter for clarification.<\/p>\n

      The Borked Scale was invented in 1998, specifically to help in assessing the criticality of a bug in a way that accommodates the widest number of perspectives.\u00a0 This scale rates two factors of a bug \u2013 its severity<\/em>, and its visibility<\/em>.\u00a0 These are measured on a scale of 1 (lowest) to 5 (highest), and are multiplied to provide a Borked<\/em> factor.<\/p>\n

      \"\"<\/a><\/p>\n

      The scale produces a Borked factor of between 1 and 25, with one being the least severe and rarest of occurrence (for instance, an off-color on a banner that is viewed by perhaps one individual user in a thousand), to the most severe and frequent (a crash that causes the user to lose data entered, which happens to practically every individual using the application or site).\u00a0 Generally Borked scores of 16 or higher are considered must-fix, and quite often are reasons for emergency patches to be issued, while scores of 4 or less may go unrepaired for the entire lifetime of the application.<\/p>\n

      Notice the outlying scores that are multiples of 5 are color-coded as critical and must-fix:\u00a0 this is because of the nature of either their severity or visibility being highest.\u00a0 Usually this means that either every single user is experiencing the problem, or those who do experience it are having the most disastrous outcome in using the system.<\/p>\n

      Expected and Actual Behavior<\/h3>\n

      This is the description of what the bug actually is <\/em>\u2013 how it behaves differently from what the user expects to happen.\u00a0 A short description of what the app does (i.e., \u201cScreen scrolls forever\u201d or \u201cError message and system locks up\u201d) versus what is expected (\u201cScreen scrolls to entry that matches search result and stops with result 40 pixels from screen top\u201d or \u201cSystem should never lock up\u201d) is to be given.<\/p>\n

      Screen Shots or Other Media<\/h3>\n

      Taking an image of the screen along the user journey to the bug can be highly valuable \u2013 these help the development staff confirm that they are following the right path to arrive at the bug.\u00a0 Users on a PC can take an image of the screen by using the \u201cPrint Screen\u201d button (on Windows, this takes an image of the entire<\/em><\/strong> screen, and places it in the Copy buffer), where it will wait to be pasted into a word doc or image-editing software with a CTRL+V key-press.\u00a0 Notice this means the entire<\/em> screen, including all background and running applications.\u00a0 If there is sensitive information there, you may wish to crop the image a bit before including it in your bug report.<\/p>\n

      Another alternative is using the key combination ALT+SHIFT+Print Screen \u2013 this will capture only the active <\/em>application in the foreground for the copy buffer.<\/p>\n

      Contact Information<\/h3>\n

      When reporting a bug, always include contact information (most systems for bug resolution include this information automatically).\u00a0 In order for any questions to be answered, the development team must be able to get in touch with the individual who first reported the bug to get first-hand information regarding the issue.<\/p>\n

      Proofreading<\/h3>\n

      Proofing your text is very helpful.\u00a0 Go back once and re-read your report before submitting it, to make sure it is understandable and intelligible.\u00a0 If possible, read it out loud to yourself and see if it sounds clear to your ear.<\/p>\n

      Professionalism<\/h3>\n

      Experiencing a bug in a program or site when you need it to work <\/em>is a frustrating experience \u2013 no one will contest that.\u00a0 However, as was stressed in the beginning of this writeup, the objective of a bug report is to repair the issue<\/em>.\u00a0 A bug report is not a place for abuse or venting.\u00a0 Chances are the individual(s) reading the report are not responsible for the problem in the first place, and an unprofessional report may be discarded or disregarded \u2013 it almost certainly will not have the attention paid to it that it deserves.<\/p>\n

      Summary<\/h2>\n

      A bug entry relies on professional, accurate and direct language describing the nature of the problem experienced, with as much assistance in locating the error as is possible to provide.\u00a0 Ultimately, its purpose is to direct development staff to the source of the problem, with a goal of providing the fastest path to repair available.<\/p>\n","protected":false},"excerpt":{"rendered":"

      Making a bug report can be a surprisingly subtle process \u2013 and precision is everyone\u2019s friend when it comes to bugs.\u00a0 In this section, we\u2019ll briefly address the most important aspects of bug reporting.\u00a0 Always remember:\u00a0 the goal of a … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-597","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/posts\/597","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/comments?post=597"}],"version-history":[{"count":0,"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/posts\/597\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/media?parent=597"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/categories?post=597"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.borkedcode.com\/wp2\/wp-json\/wp\/v2\/tags?post=597"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}