Current development on JAMWiki is primarily focused on maintenance rather than new features due to a lack of developer availability. If you are interested in working on JAMWiki please join the jamwiki-devel mailing list.

Coding Style

While coding style is a matter of personal preference, on a group project it is important that all developers follow the same style to avoid confusing inconsistencies. It's OK to make contributions to JAMWiki that don't follow this coding style, but contributors are STRONGLY encouraged to follow these guidelines, and should expect that non-conforming contributions will eventually be re-formatted by someone else so that they match the standard style. Some of the internet's greatest flamewars have been fought over coding style, so this document aims to avoid similar carnage within the JAMWiki project.

This document is liberally based on the Linux Kernel Coding Style as well as Sun's Java Code Conventions.

Contents

Indentation and Line Length[edit]

Indentations should be made with tabs, not spaces. The rationale is that tabs are configurable and obvious. Spaces have some advantages, but it's difficult to get everyone to agree on whether indentation is three spaces, four spaces, eight spaces, or whether some other number is best. And since it's easier to avoid silly debates about how many spaces to use, tabs are the solution. If you prefer eight space indentations, simply set your editor to display tabs as eight spaces.

Many people go to great trouble to make sure that code will fit on an 80 character wide screen. While that's a great and noble goal, it's pointless if it doesn't improve readability. In general if a line is getting long it's a good indication that it's not readable and should probably be rewritten, but there's no need to stress over long lines of code. Similarly, there's nothing wrong with wrapping a long line onto two lines provided it's done in a way that maintains readability. If you find a need to wrap text onto three or more lines, however, it's almost a sure sign that you're writing a line of code that people will some day be using as an example of what not to do in a book whose title ends with "For Dummies". Try to keep it short and simple, but don't freak out when a few lines cross the 80 character limit.

Braces[edit]

Braces should always be placed on the same line as the control block they are opening or closing. For example:

if (true) {
    // do something
} else {
    // do something else
}

Methods and classes are included in this rule. A method should be written as:

public void foo() {
    // body of foo
}

Statements[edit]

Only one statement should appear on each line. The following illustrates good and bad coding style:

// this is bad
int i = 1; boolean trigger = false;

// this is good
int i = 1;
boolean trigger = false;

Conditional statements should always use braces, unless the statement appears on a single line.

// this is bad
if (true)
    execute();

// either of the following are OK
if (true) execute();
if (true) {
    execute();
}

for statements should have the following form:

for (int i=0; i < max; i++) {
    // do stuff
}
// Java 5+ loops
for (Topic topic : topics) {
    // do stuff
}

switch statements should have the following form:

switch (condition) {
    case ABC:
        statements;
    case DEF:
        statements;
    default:
        statements;
        break;
}

try-catch statements should have the following form:

try {
    // do stuff
} catch (Exception e) {
    // handle exception
} finally {
    // handle finally
}

Naming[edit]

Method, class and variable names should strike a balance between descriptiveness and brevity. When looping through an iterator, "i" is preferable to "counterVariableForIterator". Variable names should not contain underscores and should begin with a lowercase letter. Variable names containing multiple words should capitalize every word after the first. For example:

  • numTopics
  • topicName

Method names should follow the same rules as those for variables. A good method name is something like "parseDocument()".

Class names are similar to method names, but the first letter of the class name must be capitalized. "DocumentParser" is a good class name.

All good rules need exceptions, and the exception to this rule is constant values. Constant values (those defined as static final) should be named using all caps and underscores. For example:

  • public static final String PROPERTY_FILE_NAME = "myprops.properties";
  • public static final int MAX_TOPICS = 10;

Hungarian notation (including a prefix on the variable name to indicate type) should not be used. If your code is so complex that special variable naming schemes are required to make it clear what variables are what types of values then you need to come up with better variable names or re-examine how your code is designed.

Methods[edit]

To quote Linus Torvalds in the Linux Kernel Coding Standard:

"Functions should be short and sweet, and do just one thing. They should fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, as we all know), and do one thing and do that well.

"The maximum length of a function is inversely proportional to the complexity and indentation level of that function. So, if you have a conceptually simple function that is just one long (but simple) case-statement, where you have to do lots of small things for a lot of different cases, it's ok to have a longer function.

"However, if you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely. Use helper functions with descriptive names."

Good indicators that a method is too complex is that it is nested more than three levels deep or contains more than two screenfuls of text. When you see those warning signs, consider simplifying the method. Strongly consider simplifying the method.

Commenting[edit]

More wisdom from Linus:

"Comments are good, but there is also a danger of over-commenting. Never try to explain how your code works in a comment: it's much better to write the code so that the working is obvious, and it's a waste of time to explain badly written code.

"Generally, you want your comments to tell what your code does, not how. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to chapter 4 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly why it does it."

Comments should, as much as possible, use standard Javadoc format.

JSP Code[edit]

Java code should never appear in JSP pages but should instead be put into a servlet or taglib. When appropriate, JSP taglibs should be used to reduce the logic contained within a JSP. The rationale here is that it's easiest when errors are caught by the compiler; putting Java code into JSP files pushes those errors onto the web application level, making them harder to find and fix. Code is going to break, but it's better if it breaks in obvious ways.

Methods should never, ever, ever be implemented from within a JSP page. Methods implemented from within a JSP page are not re-usable, do not throw compile errors until runtime, and often seem to promote bad programming habits. If you think that you've found a method that is better off being implemented in JSP rather than a Java source file you probably need to re-examine how your code is designed.

Indentation in JSP files is a matter of personal preference, but code blocks should always be aligned at the same indentation level. For example:

<c:if test="test">
    <c:if test="test2">
    <b>true</b>
    </c:if>
</c:if>

HTML Code[edit]

HTML code should align opening and closing tags on either the same line or at the same level of indentation. For example:


<table>
<tr>
    <td>table1</td>
    <td>
        <table>
        <tr>
            <td>table2</td>
        </tr>
        </table>
    </td>
</tr>
</table>

In addition, it is preferred that HTML code be valid XHTML, meaning that all tags should be closed. For example:


<!-- these are unclosed.  BAD! -->
<br>
<input type="hidden" name="hideme">
<a name="myname">

<!-- these are closed.  GOOD! -->
<br />
<input type="hidden" name="hideme" />
<a name="myname></a>

SQL Code[edit]

There is currently no overarching standard for the SQL code used in JAMWiki, but the following should be noted:

  • All table names and constraint names should begin with the prefix jam_. Using a consistent prefix makes it easier to identify objects belonging to JAMWiki in a database that serves multiple applications.
  • Thanks to DB2, database constraint names should be no longer than 18 characters. Foreign keys, primary keys, and unique keys should have the following prefixes: jam_f_, jam_p_, and jam_u_.