12 Steps to a Bigger, Better, Debugger

Think back to the first time you wrote some code. It might have been:

Or maybe:

No matter what it was, chances are the first thing you saw on your screen was:

Maybe some of you have perfect queries dripping from your fingers, and well-formed functions hopping across your keyboards. Perhaps you dine on multi-dimensional arrays and wash them down with precisely nested ifs—but I know I sure don't. If you're like me, you've probably seen more error screens than 200s.

Whether writing server-side, client-side, or regular-old-markup, you need to develop some debug muscles. Errors are an incurable side effect of human programming, and when they pop on your screen, you can probably hear your bank account draining. Become an adept debugger and you'll write cleaner apps, in shorter time.

Bigger Debuggers in 12 Easy Steps

Considering how much time we all spend debugging, it is ironic how rare a topic it is in books and conversation. So how does one become a better debugger? Hopefully, the twelve guidelines I've compiled here will help you squash bugs faster, smarter, and with more authority.

1. Organize your code.

Let's face it, building websites isn't rocket science. If you've been at it for 6 months, you've probably developed some sort of methodology. All sites share common elements, pay attention to what they are and re-use code as much as possible. Organize your code and includes so you know where everything is.

The W3C is pushing standards that separate content from structure; you'll find adopting this philosophy helps when debugging as well. Some general guidelines:

• Code once, include often.
  I'll say it again, organize your code so you know where everything is. Strive to have no duplicated code on your site.
• Externalize client-side scripts.
  Put all CSS and JavaScript into external includes. Your pages will load faster, as the scripts will go into the browser's cache. Also, you'll be able to disable all your JavaScript or all your CSS more easily. Resist the temptation from the darkside, never code CSS inline or write javascripts willy-nilly through your pages. You'll be happy later when you want to either turn it all off, or export it to another project.
• Refine it.
  Every website gains features through the development cycle. When a complex project reaches the 75% complete zone, it is usually begging, pleading, and bleeding for a rewrite. Try to take the 2, 3, maybe 4 days it will take to go back through your code and refine it when it feels out of hand. Don't be the type of a developer that has an FUNW folder for an inbox. Try to build in as much scalability as you can from the start.

2. Isolate and identify the problem.

This is the key to all debugging, and a close cousin of code organization. The problem code block must be identified, and identified quickly. If you're debugging-while-developing (DWD), you know the first place to look is the code you were just working on. If you're debugging-while-updating, or wading through someone else's work, isolation becomes more difficult.

• Trust no-one.
  Your first suspect should be the machine you're testing on. Is the error totally bizarre? Does another, known to be working page serve OK? Computers crash all the time, and test boxes that kick more errors than successes all day will tend to crash more. If you test on a *nix box, you probably find this paragraph funny. If you're on Windows, reboot your test machine at least once a day.
• Believe the error message.
  If you're reasonably sure your machine is stable, look for clues in the error message. It's funny how those messages make sense afterwards, isn't it? Line numbers in error messages are almost always wrong, but are invariably the best place to start looking. Head backwards from the line number reported, and check the nesting of that segment. When you can't find the error, comment out sections of your code until the error stops popping. Then cut and paste the problem block into a separate template for surgery.

3. Validate it!

Make the validator your home page. Writing valid HTML of some flavor is an excellent first step in error prevention. If you're new to validation, start with 4.01 Transitional. There are also many standalone tools available, the W3C maintains a list here.

4. View the source, Luke.

When you're working server-side, many times you can find problems faster by viewing what came out, rather than looking at what went in. Check the output, test variables using HTML comment blocks, or use a simple JavaScript alert to dump server-side variables. If you're dealing with a variable that changes throughout the page, output it several times.

<script language="JavaScript" type="text/JavaScript">
	alert('$some_variable');
</script>

5. Be the layout master, not the master layouter.

When dealing with a layout problem, first determine if it is an HTML or CSS problem.

• View it naked.
  Try disabling CSS, that is, if you have it in external files.
• Preview in many browsers.
  Test in whatever browsers and resolutions are appropriate throughout the entire project. Don't wait until the very end to discover your client's V.P. uses AOL 2.0 on an Amiga with a 13" monitor. HTML with syntax errors usually renders inconsistently across browsers, so if you see this behavior, inspect your HTML. Repeat step 3, and make sure your HTML validates.

6. Man-handle forms.

Everyone hates forms. If you don't, you haven't done enough multi-page checkouts yet. Bulletin boards everywhere are crawling with people having form trouble, and it's almost always related to bad-HTML or a misnamed field.

• Dissect the form elements.
  Break down the form into small chunks until you find the problem. If you're using the POST method, does the page even submit? How about with one variable? Same for the GET method, can you pass at least one variable and have it show in the URL of the target page?
• Name fields sensibly.
  If the form fields correspond to table columns in a database, use the same names for both, or adhere to some naming convention. Always build and debug server-side validation before introducing any JavaScript validation.

7. Write clean queries.

An extremely typical data-driven website scenario: You write a query in whatever, and then try to output the results. Sounds fine, but how often do you actually test the query output in its entirety? A good cabinetmaker measures twice, and cuts once. Most programmers measure a little, and hack it with an axe until it fits.

• Isolate the SQL.
  Cut and paste your SQL into its own template and run it there. Can you output anything? Write a function in your favorite server-side scripting language that auto-dumps complete result sets for you, so you can test them before you try to output them on your pages.
• Declare all columns.
  Never write SELECT * FROM table, name your fields explicitly. Even if you need every column in the table, naming them will help your templates become self-documenting.
• Run it at the source.
  Websites usually connect to databases through ODBC or some other method. At the first sign of trouble, run the query in its native program if possible.

8. Organize your variables.

Keep your local variables in a structure or array. If you store all your local variables in one object, it is much easier to dump their values onto the screen as a whole, which is an invaluable tool when debugging.

• Keep your ducks in a row.
  Every server-side language has a method for outputting complex datatypes. Store your local variables in an array or structure so you can dump them onto the screen. You might create a special footer, triggered by a URL variable, which dumps your local variables. Never put this sort of code on your live server.
• Avoid reserved words.
  RTFM and find out what the reserved words for your favorite languages are. Errors caused by reserved word misuse are difficult to diagnose, prevention is the best medicine.

9. Proceed slowly, preview often.

When you first started coding, you probably previewed every <H1>, and scrutinized every <img .../>. Typically, the more experienced programmers become the more code they'll write before previewing.

• Go slow.
  Try to find a comfortable amount of coding before previewing, so that you have a manageable chunk to work through when there's a problem. In my checkered past, I have painted houses for money. I once worked with a guy that seemed to move in slow motion, but at day's end he had always done the most work.
• Work methodically.
  Whether you like to bring all elements of a site to the same point simultaneously, or like to finish each section as you go, decide what you're going to do and stick to it. Do the hard parts first, and save the easy stuff for when you're sick of the project.

10. Mirror your test and production setups.

If you've ever uploaded files to the server with a local path unchanged, take off your left shoe and eat it. The feeling is right up there with sitting in the Principal's office, or locking your keys in your car.

• Mirror the server setup.
  Though not always possible, the advantages of having the same physical drive and folder setup as your production box are huge, and can save you hours of heartache and sweat drenched ftp sessions.
• Use absolute paths.
  Consider using absolute paths as much as possible. Avoid using the <base ...> tag, as it will inevitably lead to disaster. A long long long time ago, I uploaded a site with a <base ...> tag set to 127.0.0.1. Can you guess what happened? Everything seemed fine when I tested the uploads, because the live site was referencing my local machine. Whatever you do, don't mix absolute and relative paths—choose one and avoid the other.

11. Work like a debugger.

Make your work environment work for you. I like to hog as many machines at once as possible, coding on one and previewing on the others.

• Keep your reference books handy.
• Make sure you have video games and sugar water within reach.
• Tell noisy people to shut their pie-holes.
  Nothing clears a room like great music. If Sun Ra doesn't drive them out, I highly recommend Charles Ives' Fourth Symphony.
• Become an alt-tab, or alt-arrow ninja.
  Windows does a nice job of keeping track of your recent selections, so tabbing between your editor and browser(s) is a quickly learned skill. Soon you'll be tapping: alt-tab, ctrl-r, alt-tab, rinse and repeat. And if you're GUI-ridden, use your keyboard to navigate drop-downs in your programs, it's faster than playing with your mouse.

12. Don't waste time, take a break, ask for help!

Don't spend more than 5 minutes trying to fix something (unless you've really done it this time).

• Take a break.
  Work on something else for a while, work on nothing for a while, beat your head in with a hammer, and come back to the problem later.
• Don't go it alone.
  Sometimes a fresh set of eyes can pick up a missing semi-colon faster, so don't be afraid to ask for help when you get jammed. If you work alone, find a mailing list or bulletin board you like.

Flex Those Debuggers

Hopefully, this article has gotten you to think about how you debug, which may in turn get you thinking about how you construct your web applications. As programmers, we feed our bottomless curiosities with small victories, and fuel our fires with the burning cinders of lift-off catastrophes. So get out there, write a whole heap of errors, and be proud when you bomb the whole server.