(this post was originally written by Nick Griffith of importblogkit.com on July 15th, 2015 but sadly his website is now unavailable - it's reposted for archival purposes as it's a personal favorite)
One of my biggest pet peeves is listening to other programmers claim that a particular piece of source code simply “does not work” when they are seeking debugging help.
Claiming something “does not work” isn’t what one programmer says to another programmer. The phrase “does not work” should be reserved for when you’re taking your car to the mechanic and you don’t have a clue what’s wrong with it. If you’re telling a programmer that a particular piece of source code simply “does not work”, then you should no longer consider yourself a programmer.
There are a lot of different ways in which a piece of code could “not work”. And as a programmer, even if the solution is beyond your capabilities, the exact nature of the problem certainly shouldn’t be. If you know enough to know that the code isn’t working, you should be able to at least explain to someone else what makes you draw that conclusion.
This code does not work because…
- …it does not compile.
- …it encounters a run-time exception.
- …it does not produce the correct results.
- …it launches missiles.
Most problems fall under one of these categories. And if somehow your problem doesn’t fall under one of these categories, that doesn’t excuse you from still providing details about the nature of the problem.
If you are experiencing a problem of the nature of one of the first two in that list (does not compile or has a run-time exception), then somewhere, you’ve got an error message or an exception, and probably even a line number. This is your number one big clue as to what the problem is, and either you can find it and make some sense out of it, or who ever you’re going to ask for help will need it as necessary information in resolving your problem. And if you can’t find it? Well that’s important information too.
If your problem is that your code isn’t producing the intended results, it’s important to discuss what the intended results are exactly, what the actual results are exactly, and what the exact difference between the two actually is. This is going to be important information to anyone helping diagnose their problem. They must be clear on your actual goal. They must be clear on the actual results you are getting. And they must be clear how these two are different.
When programmers come to me and simply say “this code does not work,” I send them away. Their problem is not solvable by me or anyone. And by bringing it to me and expecting someone to solve an undefined problem, you’re wasting two people’s time.
Before you can solve a problem, you must first clearly define it. And frequently, you’ll find that in defining a problem clearly enough that others can help you, mostly you’ll just end up resolving the problem on your own.