JSP best practices

I am not implying that you cannot currently use XML with JavaServer Pages technology. I simply prefer to wait for better tools to manage the JSP-to-XML mapping as outlined in the 1.2 specification before pursuing XML-compliant JSPs (also called JSP documents). There are, however, other ways the two technologies can be used together. See Resources for articles on using XML with JSPs.

Be sure to keep abreast of the latest JSP specification and the tools your preferred vendors provide that implement that spec's new features, such as JSP-to-XML mapping. Apache provides Tomcat 4.0 as a reference implementation of the JSP 1.2 Specification.

Use JSP comments in most cases

Appropriate commenting seems to challenge software developers. JSPs, like other types of code, should include comments that describe complex or extraordinary functionality, the pages' purpose, and other general information typically commented out in source code.

Since JSPs allow developers to intermix Java, JSP tags, and HTML tags in the same page, there are multiple ways to comment a JSP page. Developers should carefully consider which type of comment to employ in the page. HTML comments will be viewable in the compiled JSP's HTML source code, and both major browsers make viewing this source easy. JSP comments, on the other hand, are not placed in the HTML document created by the JSP compilation process. These comments cannot be viewed as part of the page's source through the browser, and they do not increase the size of the rendered page's generated source. Java comments can also occur in a JSP inside Java scriptlet sections. These are not viewable in the browser either, but including Java comments in the JSP page violates the principle of separating Java from the HTML.

Code comments are usually meant for developers who write and maintain code. Therefore, use JSP comments unless there is a compelling reason to have the comments display in the browser upon request.

Note that you should not place sensitive data in JSP source code, not even inside JSP comments. Although the text inside JSP comments is not compiled into the source used to render the Webpage, Web servers might allow users to view JSP source code. Place sensitive data in a database, where access to the data can be controlled and monitored using triggers or other database mechanisms.

Follow HTML best practices

When Java is factored out of the JSP and into JavaBeans and custom tag handlers, the JSP consists mostly of JSP tags, including custom tags, and HTML tags. To make the JSP easier to understand and maintain, follow best practices related to HTML development.

One HTML best practice I follow: include closing tags recommended by the HTML specification even when the browsers do not require them. Most HTML generation tools will match opening tags with corresponding closing tags, but hand-typed HTML documents often lack closing tags (note that there is a small set of HTML tags that lack closing tags). Browsers usually render the page despite missing closing tags, but don't count on the browser to work correctly when standards are violated. Some missing closing tags, such as </table>, can dramatically affect a page's rendering in the browser. In addition, you should avoid using deprecated HTML tags, and use lowercase letters for all HTML tags.

The W3C (World Wide Web Consortium) has some resources related to HTML best practices and validation.

Utilize the JSP exception mechanism

While a thrown exception's stack trace proves extremely useful for developers when debugging their code, it is rarely desirable to share an entire exception stack trace with the software's users. Lengthy stack traces are not aesthetically pleasing and can increase security risks by exposing information that does not need to be released. JSPs allow developers to catch and handle exceptions in the code, resulting in more secure and aesthetically pleasing exception handling. See Resources for details on the mechanics of JSP exception handling.

Exception information is more useful if information besides the stack trace is included. JSPs can use session variables to store information about the current page and current operation being performed. Then, if an exception does occur, the exception page will be called; it will have access to both the thrown exception and the information about the original page that caused the exception. The exception page can utilize underlying Java code, in JavaBeans or EJBs, to store in the database the complete exception information, related session information, and the exception's date and time.

To reduce the unsightly error messages printed to the screen and improve security, the exception page need only print out a simple error message and perhaps an identifying number that allows developers to locate more detailed exception information in the database. For aesthetic and security reasons, I prefer storing most of the exception information in a database or flat file rather than printing it all to the screen. Storing the exception information in a database or flat file also allows the information to be persisted even when a user exits the application. Note that during development you should print full exception information to the screen for regular testing and debugging.

Now start developing JSPs

If abused, many JSP conveniences can lead to unnecessary complexity. This article summarizes some JSP practices that allow developers to take advantage of these conveniences without triggering unnecessary complexity. By following the best practices discussed here, you will increase your software's maintainability and reusability as well as its aesthetic qualities.

Situations might arise where the overhead of some of these recommended JSP practices is not worth the cost, such as in extremely simple applications. However, my experience is that even the simplest applications often evolve into more complex systems. In most cases, the sooner you follow best practices such as these, the better.

This story, "JSP best practices" was originally published by JavaWorld.