JavaScript The Complete Reference (2012)

PART III Applied JavaScript

CHAPTER 18 Trends and Practices

In our final chapter, we explore a few topics that are not as clearly reference material as previous chapters. Our first goal will be to put readers on, or remind them of, the path of writing better JavaScript. Some of the advice will consist of simple ideas not unique to JavaScript, while others might address the style, error, or programming techniques somewhat unique to the environment. We also take a few moments to discuss libraries. We have purposefully avoided spending much time on libraries so far in the book since we are focused on the core language and native browser and document APIs as opposed to the abstractions written on top of them. We also call out two quite important topics that plague the use of JavaScript on public-facing Web sites and applications, namely performance and security. Finally, we conclude the book almost where we started, by discussing the trends of JavaScript, particularly in light of its use.

Writing Quality JavaScript

Writing correct JavaScript syntax is a far cry from writing elegant code with JavaScript. When discussing the idea of code quality, it reminds one of the authors of the challenge of writing motivating prose more than anything. There is much one can do in writing to try to keep things interesting, but it often becomes more art than science. When it comes to writing code, it seems as though we are quick to blame the tool or language, rather than the practitioner. Somehow the “ugly” or “bad” parts of JavaScript are what caused the programmer to write awful code and not the rush of a timeline, difficulty of the problem, lack of experience, or convoluted thought process!? We’d like this argument to be true so we could then blame the English language for our struggles with writing motivating prose!

While it might be nice to blame a language for our challenges writing or coding, it just isn’t so. Certainly, a language may influence our efforts as programmers somewhat, but it is really up to us to craft good code. So we take a few moments to remind ourselves of some ideas we ought to consider when writing nice, correct, and safe code quickly. We start first with just a brief discussion of style before moving on to more practical thoughts on writing safe code and addressing errors, concluding with some demonstration of the benefits of code reuse through the use of popular JavaScript frameworks and libraries.

Coding Style

Much has been said about writing good code that is somewhat agnostic of the language it is written in, whether it is in JavaScript or not. Interestingly, we see that there is in fact no one true way to write code, despite what many may think. Even the idea of choosing a variable name can be wrought with trade-offs. Do we aim for readability?

Or do we aim for terseness, for ease of typing and speed of download?

We might find that, given JavaScript’s scoping rules, we want to add indicators of availability:

Or we might like to hint at what the variable should contain, considering JavaScript’s weak typing:

Should the value change? If it shouldn’t since we lack support for constants, we might hint at it:

Similarly, we might be employing a private property or method that we want to advise against direct invocation or access:

We might find that the terseness of writing is beneficial:

Alternatively, we might want to confuse or obfuscate what we are doing:

For better or worse, this might happen because a teacher is having fun in an example or someone is inadvertently creating some inherent job security:

To be honest, there really isn’t a clear answer to any style question. We believe we see hints as to the right direction to take in some cases. For example, in casing, we might find that following the camel-back style of JavaScript is useful:

But consider that distinguishability between our functions and those provided by the browser or host environment is not immediately obvious. We then wonder why constructor functions are initial capitalized:

Clearly, casing can be useful for more than just following a pattern. It has trade-offs as clear as the choice of names.

We can fight about whitespace, nesting, and braces, arguing the merits of doing this:

We can even acknowledge that, in certain ways, omitting the braces altogether makes the most sense, at least for simple examples:

It should be clear with our examples that we could go on for pages, showing just how pointless is this exercise to find some clear winner for how to write code (or prose). There really are good reasons for everything, depending on the context. There are times when being explicit is useful and times when it isn’t.

You might think we are aiming too low in this discussion. Instead, maybe we should debate the merits of large-scale coding problems. Is object-oriented programming (OOP) clearly more appropriate than, say, procedural-style or functional coding? That question really isn’t a foregone conclusion if you’ve ever had the pleasure of staring at a wall-sized diagram showing the relationships of objects in a relatively simple program. In that case, the particular programmer was not practicing quality OOP but instead something different, where we move the letter “P” to the front of the acronym. The same could be said for the five-line brain-teasing chained functions with tons of implied iteration or even recursion. Sure, it’s elegant, but can you figure it out a week later?

Even beyond the bad programmer problem, determining the best way at the high level is just as mixed of an answer as when posed for coding constructs. Consider that the beautiful object inheritance pattern or recursive function comes with a price. At scale, the memory weight, stack size, scope resolution time, and other side effects of high-level beauty might come at a performance price that’s just too steep for success. Yet untangling some straight-line code with every trick in the book might be both a debugging nightmare and a support impossibility. Sure, your code works, but it is a giant ball of mud now! There is only one thing that is sure—trade-offs always exist.

Seriously, though, we really aren’t trying to give up. You should be thoughtful and consistent in how you end up coding, both at the high object or algorithm level as well as at the statement level We also must acknowledge that our style choices can quickly spill into syntax or safety issues. Poorly chosen names might not just confuse, they might collide with existing properties in the host environment or any included code. Verbose clear code without modification might affect download. Code written in a literate style may not minify without breaking. Comments aimed to be helpful for future maintainers might be read by nefarious individuals bent on exploiting such useful information, and on and on we see that the way we write our code does matter.

So we question, does a particular style support some primary goal of the code? If the JavaScript needs to be continually maintained by others over a long time, our style should be readable and heavily documented. If our code must be fast, it may need to be optimized. If it needs to be safe, it may need to be wordy and careful in all its checks. If it needs to be protected, it might need to be obfuscated. Fortunately, we tend to find that in the case of performance and security, tools can help us focus less on writing for such concerns but more for future readers as they can optimize or obfuscate for us. In this sense, the best route for writing code is less for elegance than for clarity. Verbosity might be alright in naming and approach if it helps readability, though if it is too wordy, it will hurt. Whatever we do, we want to be clear, and if we can’t we must document what is going on.

Comments and Documentation

As we have seen throughout the book, JavaScript usage in Web sites can be very sophisticated. JavaScript can be used to build large, class-based applications, and it is not unusual to see an application span multitudes of files and thousands of lines.

By now, we should know that JavaScript supports two types of comments:

• Single-line comments starting with //: var lives = 9; // number of cat lives

These run to the end of the current line only.

• Multiline comments wrapped in /* and */: /*

While, syntactically, there isn’t much to say about commenting other than that it is necessary to avoid nesting them, usage-wise, there is quite a bit to say. Obviously, the purpose of commenting is to illuminate the meaning of some part of the code, include license or legal information, or—in the case of many large programs—create documentation from the source code. We look at this idea to encourage readers unfamiliar with the approach of commenting for documentation to utilize it more.

The basic idea of commenting for documentation is to embed special comments directly in source code and then have a tool generate documentation from the contents of these comments. Currently, one popular syntax for accomplishing this is JSDoc. JSDoc derives from JavaDoc, which does the same thing for Java applications. There are a number of tools for converting JSDoc into documentation. In the context of this chapter, we will be using the JSDoc Toolkit (http://code.google.com/p/jsdoc-toolkit/), but the syntax should work for any JSDoc tool.

Documentation is added directly in the JavaScript source files using comments. The comments are of the following form:

The comments have a number of tags to indicate what is being documented. To give readers a sense of what might be included within JSDoc-formatted comments, Table 18-1 shows all of the available tags.

Table 18-1 Summary of JSDoc Comment Tags

The top of a JavaScript file includes information about the file. There are a few tags that can be used to describe the page’s contents:

Documenting functions starts with a description that can be provided as the first line of the comment with no tag or with the @description tag. It includes @param tags for each function argument. The @param tag follows this format:

Only the paramName is required.

Finally, the function documentation will include an optional @returns line that will indicate what is being returned from the function. This line is of the following format:

Both returnType and returnDescription are optional.

A documented function will look like the following:

Documenting a class occurs in a similar fashion. A @constructor tag is used to indicate that a function is the constructor for a class. Then @property tags can be used to describe the properties of the class. The @property tag is identical to the @param tag:

Only the propertyName is required.

Once you finish adding comments to your script, you can run a JSDoc tool on the code. The tool will generate an API file, as shown in Figure 18-1. The file is typically in HTML, but some tools support other formats.

Figure 18-1 Sample JSDoc output

Understanding Errors

All programmers make mistakes, and a large part of becoming a more proficient developer is honing your instincts for finding and rooting out errors in your code. Debugging is a skill that is best learned through experience, and although basic debugging practices can be taught, each programmer must develop his or her own approach. In this section, we cover tools and techniques that can help you with these tasks.

Turning on Error Messages

The most basic way to track down errors is by turning on error information in your browser. By default, Internet Explorer shows an error icon in the status bar when an error occurs on the page:

Double-clicking this icon takes you to a dialog box showing information about the specific error that occurred.

Because this icon is easy to overlook, Internet Explorer gives you the option to automatically show the Error dialog box whenever an error occurs. To enable this option, select Tools | Internet Options, and click the Advanced tab. Check the “Display a Notification About Every Script Error” box, as shown here:

The other major browsers send error messages to a special window called the JavaScript Console. You can view the Console by pulling it up in the Tools menu. In Firefox, it’s under Tools | Web Development | Error Console. Under Chrome, it’s under Tools | JavaScript Console. In Safari, it is necessary to first enable the Develop menu in the Advanced menu of preferences. Then view the console by going to Develop | Show Error Console. Finally, under Opera, it’s at Tools | Advanced | Error Console. Since these browsers give no visual indication when an error occurs, you must keep the JavaScript Console open and watch for errors as your script executes.

Error Notifications

Error notifications that show up on the JavaScript Console or through Internet Explorer dialog boxes are the result of both syntax and runtime errors. Loading a file with a syntax error such as var myString = “This string doesn’t terminate results in the error dialog and JavaScript Console messages in Figure 18-2.

Figure 18-2 Example error messages—dialog and console

A very helpful feature of this kind of error reporting is that it includes the line number at which the error occurred. However, you should be aware that, occasionally, line numbers can become skewed as the result of externally linked files. Most of the time, error messages are fairly easy to decipher, but some messages are less descriptive than others, so it is useful to explicitly mention some common mistakes here.

Types of Errors and Mistakes

If we are going to address our errors reasonably, we need to explore the multitude of errors that may be encountered. So, before launching into a discussion of how JavaScript errors can be found and handled, it is useful to understand the taxonomy of errors found in typical scripts. The wide variety of errors that can occur during the execution of a script can be roughly placed into three categories: syntax, runtime, and semantic errors.

Syntax Errors Of the three types of errors, syntax errors are the most obvious. They occur when you write code that somehow violates the rules of the JavaScript language. For example, writing the following is a syntax error because the * operator requires two expressions to operate on, and “y +” does not constitute a valid expression:

Another example is shown here, where the string literal isn’t properly quoted:

Syntax errors are generally fatal in the sense that they are errors from which the interpreter cannot recover. The reason they are fatal is that they introduce ambiguity, which the language syntax is specifically designed to avoid. Sometimes the interpreter can make some sort of assumption about what the programmer intended and can continue to execute the rest of the script. For example, in the case of a nonterminated string literal, the interpreter might assume that the string ends at the end of the line. However, scripts with syntax errors should, for all intents and purposes, be considered incorrect, even if they do run in some manner because they do not constitute a valid program and their behavior can therefore be erratic, destructive, or otherwise anomalous.

Luckily, syntax errors are fairly easy to catch because they are immediately evident when the script is parsed before being executed. You cannot hide a syntax error from the interpreter in any way except by placing it in a comment. Even placing it inside a block that will never be executed, as in the following example, will result in an error:

The reason, as we have stated, is that these types of errors show up during the parsing of the script, a step that occurs before execution.

You can easily avoid syntax errors by turning on error warnings in the browser and then loading the script or by using one of the debugging methods discussed later in this chapter.

Runtime Errors The second category of errors are runtime errors, which are exactly what they sound like: errors that occur while the script is running. These errors result from JavaScript that has the correct syntax but that encounters some sort of problem in its execution environment. Common runtime errors result from trying to access a variable, property, method, or object that does not exist, or from attempting to utilize a resource that is not available.

Some runtime errors can be found by examining the source code. For example, this results in a runtime error because there is no allert() method of the Window object:

This example constitutes perfectly legal JavaScript, but the interpreter cannot tell until runtime that invoking window.allert() is invalid, because such a method might have been added as an instance property at some previous point during execution.

Other kinds of runtime errors cannot be caught by examination of source code. For example, while the following might appear to be error-free,

what happens if the user enters a negative value for choice? A runtime error indicating the array index is out of bounds.

Although some defensive programming can help here, the reality is that you cannot catch all potential runtime errors before they occur:

You can, however, catch them at runtime using JavaScript’s error and exception handling facilities, which are discussed later in the chapter.

Semantic Errors The final category of errors, semantic errors, occur when the program executes a statement that has an effect that was unintended by the programmer. These errors are much harder to catch because they tend to show up under odd or unusual circumstances and therefore go unnoticed during testing. The most common semantic errors are the result of JavaScript’s weak typing; for example:

If the programmer intended add() to return the numeric sum of its two arguments, then the preceding code is a semantic error in the sense that mySum is assigned a string instead of a number. The reason, of course, is that prompt() returns a string that causes + to act as the string concatenation operator, rather than as the numeric addition operator.

Semantic errors arise most often as the result of interaction with the user. They can usually be avoided by including explicit checking in your functions. For example, we could redefine the add() function to ensure that the type and number of the arguments are correct:

Alternatively, the add() function could be rewritten to attempt to convert its arguments to numbers—for example, by using the parseFloat() or parseInt() functions.

In general, semantic errors can be avoided (or at least reduced) by employing defensive programming tactics. If you write your functions anticipating that users and programmers will purposely try to break them in every conceivable fashion, you can save yourself future headaches. Writing “paranoid” code might seem a bit cumbersome, but doing so enhances code reusability and site robustness (in addition to showcasing your mature attitude toward software development).

Common Mistakes Table 18-2 indicates some common JavaScript mistakes and their symptoms. This list is by no means exhaustive, but it does include the majority of mistakes made by novice programmers. Of these errors, those associated with type mismatches and access to form elements are probably the hardest for beginners to notice, so you should take special care when interacting with forms or other user-entered data.

Table 18-2 Common JavaScript Errors

Using some sort of integrated development environment (IDE) or Web editor that matches parentheses and colors your code is often helpful in avoiding syntax errors. Such programs automatically show where parentheses and brackets match, and provide visual indications of the different parts of the script. For example, comments might appear in red, while keywords appear in blue and string literals appear in black.

Debugging

Although turning on error messages and checking for common mistakes can help you find some of the most obvious errors in your code, doing so is rarely helpful for finding semantic errors. There are, however, some widespread practices that many developers employ when trying to find the reason for malfunctioning code.

Manually Outputting Debugging Information

One of the most common techniques is to output verbose status information as the script runs in order to verify the flow of execution. For example, a debugging flag that enables or disables debugging output included within each function might be set at the beginning of the script. The first way to output information in JavaScript is using the alert() method; for example, you might write something like this and include alert() messages marking the flow of execution in swapImages():

By examining the content and order of the alert() messages as they appear, you are granted a window to the internal state of your script.

Having many alert() messages when debugging large or complicated scripts may be impractical (not to mention annoying). In addition, it is not possible to examine an object deeply without writing code to enumerate through the object. Luckily, most modern browsers now offer the Console window previously discussed, and it is possible to write directly to the Console window using console.log, console.info, console.warn, and console.error. When writing an object to the console, it is possible to open the object up and inspect the properties and methods:

Stack Traces

Whenever one function calls another, the interpreter must keep track of the calling function so that when the called function returns it knows where to continue execution. Such records are stored in the call stack, and each entry includes the name of the calling function, the line number of invocation, arguments to the function, and other local variable information. For example, consider this simple code:

At the document.write in a(), the call stack looks something like this:

a(12), line 3, local variable information…

b(11), line 7, local variable information…

c(10), line 11, local variable information…

When a() returns, b() will continue executing on line 8, and when it returns, c() will continue executing on line 12.

A listing of the call stack is known as a stack trace and can be useful when debugging. Many browsers provide the stack property of the Error object for just such occasions. We can augment our previous example to output a stack trace in supporting browsers:

The output is shown here:

The top of the trace indicates that the function that called the error constructor is a() and its argument was 12. The other data on the line indicates the filename where this function is defined (after the @), as well as the line number (after the colon) the interpreter is currently executing. Successive lines show the calling functions, as we’d expect, and the final line shows that c() was called on line 20 of the currently executing file. (The call to c() isn’t within any function, so the record on the stack doesn’t list a function name.)

Using a Debugger

A debugger is an application that places all aspects of script execution under the control of the programmer. Debuggers provide fine-grained control over the state of the script through an interface that allows you to examine and set values, as well as control the flow of execution.

Once a script has been loaded into a debugger, it can be run one line at a time or instructed to halt at certain breakpoints. The idea is that once execution is halted, the programmer can examine the state of the script and its variables in order to determine if something is amiss. Debuggers also allow you to examine stack traces—that is, the call tree representing the flow of execution through various pieces of code, which we saw in the previous section. To top it all off, debuggers are often programmed to alert the programmer when a potentially problematic piece of code is encountered; and because debuggers are specifically designed to track down problems, the error messages and warnings they display tend to be more helpful than those of the browser.

There are several major JavaScript debuggers in current use. The most popular free debugger is Firebug, which was originally built as an add-on for Firefox but now has versions for all major browsers. It integrates with the browser and offers all of the features most developers might need, including a profiler enabling you to measure the performance of your code.

Most major browsers now have a debugger built directly into them. These debuggers are included in the browser and are easy to activate. For example, the Chrome Developer Tools can be accessed through Tools | Developer Tools. As we can see in Figure 18-3, we can use them to view errors, inspect Web page elements, set up breakpoints, watch network activity, and monitor performance.

Figure 18-3 Example of JavaScript developer tools for debugging

When using the debugger, it is possible to go to the script that is buggy and put breakpoints in through the tool. However, this requires a reload if the buggy code is executed on load. It also requires finding the spot in the code within the debugger tool, which isn’t always the easiest thing to do. Luckily, all the major debuggers support the debugger statement, which invokes a breakpoint right when it is encountered. This leads to easy interaction between the code and the debugging environment, as shown in Figure 18-4.

Figure 18-4 Using a debugger

Now that we have covered some tools for tracking down errors in your code, we turn to techniques you can use to prevent or accommodate problems that might be outside of your direct control.

Defensive Programming

Defensive programming is the art of writing code that functions properly under adverse conditions. In the context of the Web, an “adverse condition” could be many different things: for example, it might be a user with a very old browser or an embedded object or frame that gets stuck while loading. Coding defensively involves an awareness of the situations in which something can go awry. Some of the most common possibilities you should try to accommodate include the following:

• Users with JavaScript turned off

• Users with cookies turned off

• Embedded Java applets that throw an exception

• Frames or embedded objects that load incorrectly or incompletely

• Older browsers that do not support modern JavaScript objects or methods

• Users with text-based or aural browsers

• Users on non-Windows platforms

• Malicious users attempting to abuse a service or resource through your scripts

• Users who enter typos or other invalid data into form fields or dialog boxes, such as entering letters in a field requiring numbers

The key to defensive programming is flexibility. You should strive to accommodate as many different possible client configurations and actions as you can. From a coding standpoint, this means you should include HTML (such as <noscript>) and browser-sensing code that permit graceful degradation of functionality across a variety of platforms. From a testing standpoint, this means you should always run a script in as many different browsers and versions and on as many different platforms as possible before placing it live on your site.

In addition to accommodating the general issues just described, you should also consider the specific things that might go wrong with your script. If you are not sure when a particular language feature you are using was added to JavaScript, it is always a good idea to check a reference to make sure it is well supported. If you are utilizing dynamic page manipulation techniques or trying to access embedded objects, you might consider whether you have appropriate code in place to prevent execution of your scripts while the document is still loading. If you have linked external .js libraries, you might include a flag in the form of a global variable in each library that can be checked to ensure that the script has properly loaded. It is also a good idea to use namespacing when using external libraries to prevent any variable name collision.

The following sections outline a variety of specific techniques you can use for defensive programming. While no single set of ideas or approaches is a panacea, applying the following principles to your scripts can dramatically reduce the number of errors your Web pages encounter. Additionally, they can help you solve those errors that are encountered in a more timely fashion, as well as “future proof” your scripts against new browsers and behaviors.

However, at the end of the day, the efficacy of defensive programming comes down to the skill, experience, and attention to detail of the individual developer. If you can think of a way for the user to break your script or to cause some sort of malfunction, this is usually a good sign that more defensive techniques are required.

Traditional Error Handlers

Primitive error-handling capabilities are provided through the onerror handler of the Window object. By setting this event handler, you can augment or replace the default action associated with runtime errors on the page. For example, you can replace or suppress the error messages output to the JavaScript Console.

For example, to suppress error messages, you might use the following code:

Since modern browsers don’t typically display script errors unless users specifically configure them to do so, the utility of the return value is limited.

The truly useful feature of onerror handlers is that they are automatically passed three values by the browser. The first argument is a string containing an error message describing the error that occurred. The second is a string containing the URL of the page that generated the error, which might be different from the current page if, for example, the document has frames. The third parameter is a numeric value indicating the line number at which the error occurred.

You can use these parameters to create custom error messages, such as the one shown here:

It is important to note that this handler fires only as the result of runtime errors; syntax errors do not trigger the onerror handler and generally cannot be suppressed.

Automatic Error Reporting

An interesting use of this feature is to add automatic error reporting to your site. You might trap errors and send the information to a server using Ajax. We illustrate the concept with the following code. The XMLHttpRequest sends the error information to submiterror.php, which can automatically notify the Webmaster or log the information for future review, as shown in Figure 18-5:

Figure 18-5 JavaScript errors can be reported.