Tips For Software Developers on Seeking Help and/or Reporting Problems with Code They are Writing

Throughout courses I have taught, students have asked for help because some code they are writing isn't working, or they have received error messages (Java, Umple, shell scripts, etc.) that they don't understand.

Throughout any software developer's career they will encounter coding problems and need to either seek help or report problems with technology they are re-using. They might be reporting a bug in a code library their company uses, or seeking help on Stack Overflow. The principles are the same when they are when reporting problems or asking for help from a technical mentor, Stack Overflow, a TA or professor in a course.

Too often, beginners don't bother to report problems or don't do so in an effective way. I have distilled the following from dealing with way to many incomplete, unhelpful, or unneeded reports or help requests.

Things to do when you have a coding problem and feel you need help or think it might be a bug:

1. Boil the problem down to the smallest case that still has the issue. So if you have 200 lines of code with an issue, subtract  parts of the code bit by bit until the problem disappears, then add the last bit back. Keep trying to subtract other bits. See if you can submit a question or issue just related to perhaps 5 lines of code, or the smallest reasonable number that manifests the probem. To determine the bits to subtract, focus on just the changes you have made to the previous working version of the code by doing a 'diff' with the previous version.

2. Try hard to ensure you cannot solve the problem yourself first. For coding problems, clean up the remaining code after step 1 code so it is nicely indented. Check for balanced brackets and quotes. Add some comments to it (this can help you understand it and often solve your own problems). Make sure you are using the latest version of the technology (the problem may have been fixed very recently -- maybe even in the last days -- so update to the latest possible version). Check on Stack Overflow or other places in case others have asked the same problem (e.g. in the chat tool your group or company uses). Search the relevant parts of the user manual (usually online) to see if you have misunderstood something.

3. If at this point it is a defect or failure you want to report, then look in the bug-reporting system to see if it has already been reported. A Google search for <technology> bugs will normally take you to the relevant system. And a Google search for <technology> bug <description of bug> will often locate other reports. If you find another report, you might find help for working around the problem, or you might be able to add additional information that will help developers. If you don't find a report, then you can add your own issue report. Give it a very descriptive and precise title and a good initial paragraph describing the issue.

4. Submit actual code that you are having problem with, rather than (just) a screen shot. Actual code that can be copied and pasted allows the person helping you, or the person reproducing the problem to very quickly run it themselves. Eyeballing the problem on a screenshot might not be enough: Sometimes the root of the problem is somewhere else in the code, or it is a problem with 'invisible' characters. And you cannot expect the person who has the problem to type in your code. You can also send a screenshot if it somehow sheds additional light on the problem (e.g. shows the error in context), but the actual code is critical. If you are sending error messages that refer to a line of code, make sure the lines numbers are visible in any screenshots.

5. If the problem involves a user interface, send at least one screenshot of that. Remember that usability difficulties are legitimate problems to be reported, or to seek help about.

6. If the problem is on the web, check if it occurs in at least 3 browsers (Chrome, Firefox, Edge, Safari, Opera), and report any differences. It maybe a browser incompatibility.

7. Make sure you carefully describe relevant aspects of your setup: Operating system and version, programming language or library version installed (e.g. result of java --version), browser version(s), IDE used, environment variables set.

8. Describe any inputs or steps that need to be done to reproduce the problem. This includes command line arguments, compilation steps, etc.

9. If it is not obviously an error you are reporting or asking about (e.g. if it is something you are trying to achieve), then describe in sufficient detail what you expect to happen or are trying to make happen,


Above all! Report. Don't just let problems lie there. Be proactive in reporting problems. It is your professional responsibility. So many times I have heard reports like, "All 100 of us had that problem, and we spent ages trying to work around it". The problem may have had a 10-minute fix and the developers may be very greatful to get the report.