Trouble Shooting Best Practice

A good Best-Practice document summarised per discussion with Mike Thompson, the best engineer I’ve ever worked with in EMC.

What are the good practices when you write bug/feature description or bug/feature comments?
  1. Write for your audience. Think about wording from the reader’s point of view.
  2. Write for the future. Think about any current context that is needed to understand the words.
  3. Post summaries of offline discussion, instead of discussion itself (email, IM log etc.).
What we should pay attention to during the initial triage?
  1. Are there too many problems described? One problem, one ticket.
  2. Is support material (Steps to reproduce, Screenshot, Log etc.) available? If yes, make a quick analysis.
  3. Is this an obvious duplicate/regression?
  4. Validate/Clarify steps to reproduce.
What shall we consider before we start extensive code change?
  1. Make a review of our root cause analysis.
  2. Make a review of our solution design.
During code review, what are the 2 questions that reviewers should keep on asking themselves?
  1. Why. Why this solution? Why this code? Etc.
  2. Why not. Why not that solution? Why not that code? Etc.
What we should pay attention to when reviewing the problem solution?
  1. The problem is analyzed correctly. The real defect is found.
  2. The solution is correct & best for this problem, among other solutions.
  3. The solution is correctly implemented. No code error.
  4. If the problem is a regression, the regression causing bug/feature should be identified, and that bug/feature’s fix should not be breaked.
Root cause should be described precisely. What are the good practices for root cause description?
  1. Identify any pre-conditions required for the defect.
  2. Identify what is the expected outcome and what is the actual result.
  3. Describe why is the actual result. Write for the audience and write for the future.
  4. Identify when the defect is introduced into the system, especially if it is a regression.
If there is one problem, we know how the symptom is produced, and our code change can prevent the symptom, is that good enough? Why

No, creating an effective bug fix requires correctly identifying when the defect was introduced, and why it was introduced. Investigating on the code history and get the reason of regression is very important; it may influence the solution design.