I know, I'll use a library! Now you have two problems

I just helped a co-worker from another dept debug one of those fun bugs that make absolutely no sense when you first see it (syntax error in IE6, no line number, if you're wondering). The codebase is for an internal app and it's fairly old and not very well written. It uses an older version of prototype and uses Adobe's js library to get around that Eolas thing.

So, just like the adobe code docs suggested, we had code like this:

<script type="text/javascript">
<!--
var bla = "some config for flash player version"
-->
</script>

Yeah, we know inline javascript is not a great idea, but people working with 3rd party flash graph components (especially when these people are full-time back-enders) are not particularly keen on iterating over little javascript boilerplates that are just there to get the flash up and running.

Anyways, the code above looks fairly harmless. It's just a variable assignment.

Or is it? Turns out that if we ajax that code with older versions of prototype, the Ajax.Updater call will internally parse all the script tags and eval() their innerHTMLs via the String.evalScripts function. The catch: it doesn't filter out the HTML comments out!

So, since IE6 doesn't have support for E4X, you'll get a big fat syntax error popup on your face.

Yes, I admit, our internal code is fairly ugly and could be improved a lot, but that's another rant. The issue here, though, is that, by themselves, both Prototype and the Adobe library worked just fine - it's only when the two appeared in the same codebase that hell broke loose.

Now that I've described the problem, it may even seem fairly silly and easy to identify, but tell that to the guy that was pulling his hair out a few hours ago. In all honesty, we only managed to find out that was the issue because:

1. I've played a lot with writing libraries on my spare time and I know about many browser limitations and quirks that you can only know if you actually do a ton of cross-browser debugging (rather than just staying inside the comfort zone of a tested js library)
2. I read a whole lot more open source code than a lot of my co-workers and, as such, I'm fairly well versed with Prototype's finicky hacks.
3. We had already tried a bunch of other things and I suggested to try something unintuitive, because I was stumped and the old school HTML comment in the script tag was about the only thing left that looked even remotely unusual.

Not understanding enough about what's hidden by a library's layer of abstraction can be dangerous. It makes it hard to troubleshoot a problem, even when you can see the faulty code right in front of your eyes.

So do yourself a favor and read the code for the libraries you use. You'll likely learn a bunch of stuff you didn't know before, and sooner or later, instead of burning yourself out over some inexplicable bug, you'll have a moment of enlightenment and say "hey, I know what's the problem here!".

At least for me, whenever it did happen, the second option has been great.