Troubleshooting Tips for Developers

I often train several developers/programmers/software engineers and have seen many of them have the tendency to run for help on seeing the word ERROR without even reading the error message properly.

So I prepared these guidelines which I feel can enable many developers to troubleshoot coding issues independently and reach for assistance only when necessary.

1. Whenever you face any error, Don’t immediately send out a Mayday call!​​
2. Do the below things BEFORE reaching out for help.​​
3. ALWAYS read the error message/log carefully — word by word.
4. Try analyzing/recalling any recent changes that would have introduced the error. ​​(Not necessarily made by you, Many times it could even be that upgrade by the sysadmin/it/ops team)
5. Google the EXACT error message/code.
6. Revisit official documentation for details on when this error message is generated. make sure you are passing the right arguments/configuration/syntax, according to the version of the language/service/plugin/provider/tool you are working on.
7. Sites like StackExchange, github.com issues, Reddit often have threads of similar issues​​. It’s quite likely someone would have faced a similar issue before​​. (There are several geeks/more experienced programmers out there who are happy to help, in exchange for — nothing)
8. If you find it on github.com issues, and the issue is still open — Check any open PRs that can give you a clue.
9. It's important to identify the ROOT cause of the error and reproduce it consistently to seek help. ​
10. Usually try one solution/change at a time, to know what exactly fixed the issue
11. Make sure you are not leaving dead code/commented code blocks when you try multiple approaches.
12. Rebooting/Restarting service/server may fix it, but not recommended, as you may never know the root cause or the solution. (And a skeleton in the cupboard can always come back to haunt you on a scary night. Often at the worst possible time. )
13. Usually, the FIRST LEVEL of troubleshooting should be done by you using the steps described above​​
14. SECOND LEVEL, Check with your peer developers if anyone faced a similar error. ​​
15. I also recommend maintaining a common tracker in some centrally accessible wiki within your team/group for tracking common issues and solutions. Sometimes we troubleshoot an issue months before and then completely lose context of steps taken to fix it. ​
16. It’s better to clearly articulate the problem statement, the steps to reproduce the same error (without ANY typos), and the steps you have taken so far to resolve it. Quite often — trying to articulate a problem clearly helps you solve it.
17. LEVEL THREE, reach out to more experienced members/known experts within your organization with your problem statement through internal forums. If they are not available due to meetings/project work, they can look into it and respond as per the availability. ​​
18. Otherwise, you can post the issue on public forums like stack-exchange (after making sure you sanitize/mask the confidential contents) where you may find some good samaritan always willing to help. Most programmers may be known to be socially awkward, but all of them truly get a high out of solving puzzles no human has solved before.
19. If all steps above still don't solve the puzzle, then make sure you DON’T spend too much time stuck on an issue, (set a time limit), try to find a workaround, or focus on developing other features to continue making progress​​. (I have never seen a dev team with an empty backlog! )
20. Remember to NEVER have very long troubleshooting sessions individually or with peers. Taking a tea/coffee break or a breath of fresh air is often what you need to catch a silly mistake!

Closing Thoughts —
While all the above tips may help you resolve issues after they happen, it's also important to keep in mind why most errors are introduced.

In my opinion, sometimes developers resort to the below practices in an effort to save time but end up being the reason behind letting a lot of time, effort, and energy go down the drain. (Not only their own but of many ppl around them)

1. Pushing too many changes in a single commit. It's always recommended to make small incremental functionally cohesive commits. If you follow this practice you may only need to investigate the last commit to fix most issues.
2. Copying and pasting code from others without taking the effort to understand it. (Especially from StackExchange) I can’t stress enough about the side effects of this approach. Even if you are lucky enough to find a code snippet from a thread last active in 2012 that still works, you may have possibly introduced a security vulnerability that can cost you your job and your company the client.
3. Not commenting code, using commit messages like “fixed issue/made changes”, hesitating to write code from scratch. (Trust me! It's not as difficult as it sounds, and being able to fluently write code from scratch only gets easier with time)

Happy Coding!!