This morning, we posted a draft set of recommendations on Coding Conventions for the JavaServer PagesTM Version 1.x Language. The article can be found here:

http://developer.java.sun.com/developer/technicalArticles/javaserverpages/code_convention/

The article is intended to be a first draft of coding conventions, and we're getting some great, high-quality feedback on our comments alias, jsp-codeconv-comments@sun.com. Keep 'em coming!

This alias is one-way only (from you to us), and we'd love to see a more collaborative feedback forum as well. I've started this topic as a place so that users can discuss and share their experiences with JSP coding conventions, as used in their organizations.

Please continue to send feedback to jsp-codeconv-comments@sun.com as well!

--
Mark Roth, Java Software
Specification Co-Lead of JSP 2.0
Sun Microsystems, Inc.

 

 

A few suggestions:

1. Re:


Since web resources can be more than images. (e.g. .wav sound files, .mov quicktime movies, .sfw Shockwave Flash applets), would it be better to name the folder "mutimedia/", or "objects/" rather than images? It may often make sense to group multimedia together in the same folder rather than create separate folders for "audio/", "videos/", "flash/", etc.


2. As for opening comments, would it better to use xml tags such as <author>...</author>, <description>...</description> within the comments as that would make it easier for scripts automated programs to extract meta data from the .jsp pages?

3. (Forgive me if this one is silly :-) Isn't .htm easier than .html? If someone is viewing the page on an old OS which only supports 3 letter extensions, it may be easier to save the .htm file with the same extension.

4. Isn't the include format below still better since it does not generate extra linefeeds? It would be better if JSP didn't generate linefeeds where the author didn't intend, especially if the .JSP is generating "Content-type: text/plain" or some other format output.

<%@ page session="false"
import="java.util.,java.text.,
com.mycorp.myapp.taglib.,
com.mycorp.myapp.sql., ..."
...
%>

 

 

The spec needs to cover i18n using a single JSP file and the fmt: part of the JSTL (or its predecessor, the i18n taglib from Jakarta). We used to use the directory-and-multiple-files form of i18n, but our customers didn't like it, preferring a single file with the contents localized.

Until you get to localizing the actual layout (more than can be handled by the <ltr> tag) and visual design of the pages, using the fmt: tagib works much better.

Also, the draft makes an all too common mistake of specifying a fully-qualified locale as the directory name instead of using the broadest appropriate locale like you do with Java properties files. So, instead of "en_US" you would want to use "en" since us en_CA and en_GB types can handle words spelled with 'z's instead of 's'es.

 

 

It might just be me, but using subdirectories with names (css, tld, js) that just duplicate the extension of the files they contain is redundant. The extension is more than sufficient to find and identify those files.

 

 

Having a comment (even server side) at the start of the file is
something we have learned not to do. Server-side comments are not
completely transparent, since they inject one line into the output per
line of comment. This can cause problems with the output buffers. They
have to be placed at the end of the file to be safe, especially when
emitting XML documents.

 

 

The spec should probably not cover indentation, since indentation does have an effect on the ultimate display of HTML. There are many, many cases where you cannot have spaces or line-breaks between tags if you want to get the HTML to display the way you want. This sentence is actually false: "The additional indentations, however, are usually ignored (by the browser) and have no effect on the rendered output on the browser."
"Pretty" indentation of tags is a nice idea, but doesn't work in practise for documents outputting HTML.

 

 

Another thing the spec should cover is what are the implications of @include and jsp:include. Using @include you rapidly hit the 64k per method limit, and jsp:include has its own quirks.

Is there any way to convince the JVM team to lift the 64k per method limit, since it's almost impossible to avoid it when using JSP? I was hoping they would correct it with the classfile changes in 1.4, but they didn't.

 

 

It might be best to keep the spec general and just say "files of other types (images, sounds, Flash) should be stored in other directories that have appropriate names such as '/images' or '/multimedia'".

 

 

I make it a habit to indent JSP and Java code independent of the HTML. The advantage of this approach is that the scope of your variables and code is far more clear.

For the example given, this would look like:

    <table>
<% if { tableHeaderRequired ) { %>
        <tr>
            <th>Last Name</th>
            <th>First Name</th>
        </tr>
<%  } %>
 
<c:forEach var="customer" items="${customers}">
        <tr>
            <td><c:out value="${customer.lastName}"/></td>
            <td><c:out value="${customer.firstName}"/></td>
        </tr>
</c:forEach>
    </table>

Especially in the case where you have loops inside loops or nested if statements, I find it greatly improves readability, since control code is separated from HTML where possible.

Regards,
Ronald Wildenberg.

 

 

Just did a copy, paste of the mail I sent to jsp-codeconv-comments:

We have been using following to suppress unneccessary newlines at the output:

<%
// $Id: $
// $Revision: $
// $Date: $
//
// Search page
//
// ==========================================================================
// $Log: $
// ==========================================================================
//            (C) Copyright 2003 New Media Juju [http://www.juju.ee]
//                            All rights reserved
//
 
%><%@ taglib prefix="ptl" uri="portal.tld"
%><%@ taglib prefix="ptt" uri="portlet.tld"
%><%@ taglib prefix="mdl" uri="model.tld"
 
%><%@ page import="com.qla.portal.i18n.I18nSystem"
%><%@ page import="com.qla.portal.search.ip.QueryResults"
%><%@ page import="com.qla.portal.search.ip.QueryResultLine"
 
%><%
       String str = "test";
 
       ...
 
%><html>
<head>
</head>
<body>
</body>
</html>

Otherwise you have lots of empty lines in the output and the generated servlet class has many unneccessary out.print("\r\n")-s. The empty lines may also be a security risk as they allow hacker to determine that you are using JSP engine and they show in which places on a web page you are doing <jsp:include>. This is of course not a great risk but anyway ...

 

 

"Compound Indention with JSP, HTML and Java"
small typo - the beginning of the if statement in both examples has a "{" between 'if' and 'tableHeaderRequired', instead of a "(".

    <table>
        <%  if ->{<- tableHeaderRequired ) { %>
            <tr>
                <th>Last Name</th>
                <th>First Name</th>
            </tr>
        <%  } %>
        <c:forEach var="customer" items="${customers}">
            <tr>
                <td><c:out value="${customer.lastName}"/></td>
                <td><c:out value="${customer.firstName}"/></td>
            </tr>
        </c:forEach>
    </table>

JavaBeans Initialization
In the third paragraph, there was mention of using a comment to note the expected parameters. I have also seen where some books recommend creating a method that will reset all the fields in the bean to get around previously set values (your First reason for caution).

JSP Implicit Objects
I was a little confused by the first paragraph. It did not become apparent until after I read the second paragraph. Could this be reworded?


Overall, a very nice document. Thx.

 

 

Doubtlessly, this article should be deemed as a great contribution to the J2EE community. However,

(A) Maybe I'm wrong, but it seems to me that there is no such thing as JavaServer Pages TM (Version 1.x) LANGUAGE, though we do have JavaServer Pages TM SPECIFICATION (Version 1.x).

(B) Coding convention is more important to a large project -- which is typically well-architected -- than to a small one. For a well-architected J2EE application, the scriptlet should be avoided. Sure, one can argue that we are talking about conventions on JSP Spec 1.x and the Spec does not require you to work this way. But for readability, debuggability, maintainability and many other reasons, you may want to have a script-free page as mentioned in a few places in the article. I would be more than happy if the article could be re-organized by
(B1) grouping the scriptlet related conventions together and putting them into a special section
(B2) adding a TOC

 

 

I've used a similar format for a technical reason - the only way I found to output binary data in a jsp is by using response.getOutputStream(). If there are any blank lines output before this call, an IllegalStateException is thrown. the only way to output binary data in a jsp is by using such tags with absolutely no whitespace anywhere.

 

 

The JSP guidelines suggest that

"Indentations should be filled with space characters. Tab characters cause different interpretation in the spacing of characters in different editors and should not be used for indentation inside a JSP."

It is a simple observation that using spaces instead of tab characters increases the returned content length. While this may seem insignificant, in my opinion it is not. for example, checking the trivial table sample in the guideline:

<table>
<% if { tableHeaderRequired ) { %>
<tr>
<th>Last Name</th>
<th>First Name</th>
</tr>
<% } %>
<c:forEach var="customer" items="${customers}">
<tr>
<td><c:out value="${customer.lastName}"/></td>
<td><c:out value="${customer.firstName}"/></td>
</tr>
</c:forEach>
</table>

using tabs in indentation results in 329 bytes of data, while using spaces results in 443 bytes, or about 35% more data! Testing on several real-world pages gave similar results. While this this certainly varies with content and coding style, following the indentation guidelines, which are extremely important for readability, will result in several indentation levels in an avarage line of nontrivial code, and an increase in data size of similar proportions. In my opinion this increase in traffic and processing is quite significant in a production server. Or, as I like to think of it, imagine an internet where all web servers were jsp-based, and that all web transactions were 35% slower...

Finally, the stated reason that 'Tab characters cause different interpretation in the spacing of characters in different editors' doesn't seem like a very strong case. Developers who want to view JSP sources are most likely JSP developers, which should have their editors or IDEs set to 4-space tabs in the first place, as the guideline suggests. Perhaps some editors I'm not aware of don't allow these settings, which can cause the stated problem.

I wonder if these consequences were taken into account when deciding on the guidelines.

Other than that, I think the guidelines are great, and as with the other Java programming convention guidelines, I hope they reach widespread use and become standard developer practice, for the benefit of all.

-Amichai

 

 

Good start. An issue I would like to see specifically mentioned is the naming of input fields. On the Java side one needs to get specific request parameters. The names of these parameters must match between a JSP page and a Java program that extracts the parameter from the request.

One technique is to define constants for the request parameter names, and then define your input field like this:

<input name="<%= Constants.PATH%>">

The article recommends against the use of <%= %>.

By using a tag one could code this instead:
<input name='<myTags:constant name="PATH"/>'>

But you lose the compile time check.

Any thoughts?

Since this is a common issue, I think it should be specifically mentioned.