XBN Java: Coding Standards

`XBN` Java: Coding Standards

<< BACK to xbn document home

The Java coding standards I use in the xbn packages are an (almost perfect) extension of Sun Microsystem's Code Conventions for the Java Programming Language.

Contents:

... xbn Specific Coding Standards: Things I do, above and beyond the official standards.
... Exceptions: Things in the official coding conventions, but done somewhat differently by me.

TOP Exceptions: Things in the official coding conventions, but done somewhat differently by me

Contents:

... 3.1.1 Beginning Comment
... 3.1.2 Package and Import Statements
... 5.2 JavaDoc Comments

BACK 3.1.1 Beginning Comment

Official documentation

Only use asterisks in the comment open and close tags. Do not prefix every mid-line with it. Also, tab-delimit each paragraph and do not use hard breaks mid-paragraph.

Example:

/*

      Classname



      Version information



      Date



      Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice Copyright notice

 */

This exception is the same with JavaDoc comments.

BACK 5.2 JavaDoc Comments

Official documentation

Follow the same exception ruls, as with the beginning comment. The only differences being that the open tag must contain two asterisks, and the comment itself should be formatted as html code...

   /**

      <P>This is my JavaDoc comment.  This is my JavaDoc comment.  This is my JavaDoc comment.  This is my JavaDoc comment.  <B>This is my JavaDoc comment.</B>  <I>This is my JavaDoc comment.</I>  This is my JavaDoc comment.  This is my JavaDoc comment.</P>

    **/

Note the open tag should be indented to the same level as the function header. The close tag should be indented to the same level as the open tag, plus one space. The actual comments should be indented one level beyond that.

First sentence of JavaDoc blocks should contain no links. Exceptions:

When a class or package is deprecated, a link can be provided to its replacement class/package, if one exists.
Every function and class (not package) within testing and example code should have a link to the function/class/package that is being tested (a back link should be made from every function.

BACK 3.1.2 Package and Import Statements

Official documentation

Package statements are unchanged from the official standard. It should be completely unindented, and the first line immediately following the beginning comment.

Import statements

Unless you are truly using every class in a package (or darn close), do not import '*'. It's confusing, especially when only one or two (out of 20 or 100) are actually being used.

The class that is being extended should be the first import statement, with a single indent. All other imports, aside from exceptions, should be two indents, grouped by major package prefix, and listed roughly alphabetically within each group.

Exceptions should be at the bottom of their respective package group, with three indents, and listed alphabetically.

For all other imports, each major package groups listed (generally) alphabetically, and each separated by a space. Exception imports should be at the end of their reps

Here are the import statements for Utility.java:

package xbn.util;
	import xbn.XBNObject;
		import xbn.array.VWObject;
		import xbn.array.VWString;
		import xbn.array.primitive.PASString;
		import xbn.array.primitive.PARString;
		import xbn.array.primitive.PARDupNullLen;
		import xbn.array.primitive.PAROrderDir;
		import xbn.output.Outputter;
		import xbn.placeholder.i_i_i;
		import xbn.placeholder.s_acs_acs;
		import xbn.string.FLRString;
		import xbn.string.SOBStringBuffer;
		import xbn.string.StringOrBuffer;
		import xbn.string.UtilSOB;
		import xbn.string.UtilString;
		import xbn.string.UtilStringBuffer;
			import xbn.AssertException;

		import java.io.BufferedInputStream;
		import java.io.InputStream;
		import java.io.File;
		import java.io.FileFilter;
		import java.io.FileInputStream;
		import java.net.URL;
		import java.util.Enumeration;
		import java.util.Hashtable;
			import java.io.FileNotFoundException;
			import java.io.IOException;
			import java.net.MalformedURLException;

TOP `xbn Specific Coding Standards:` Things I do, above and beyond the official standards

Contents:

... Import statements
... Non-parameter variable names (including finals/constants)
... Parameter variable names
... Line length

BACK Line length

The length of any single line comment should not exceed character 65, including trailing tabs/spaces.

BACK Non-parameter variable names (including finals/constants)

All (non-parameter) variables should be prefixed with an abbreviation of the variables type, followed by the descriptive name, with each word starting with a capital letter, and not separated (separated by nothing). Examples:

sThisIsAString
iThisIsAnInt
connThisIsADBConnection
hsrThisIsAnHttpServletResponse

In only the most trivial cases should you not have a descriptive postfix. Use only the type abbreviation...

s
i
conn
hsr

`final` (Constants)

static final variables have the same rules as non-static-finals, except the descriptive postfix should be all uppercase, with each word separated by an underscore. The type prefix abbreviation and the first descriptive postfix word should not be separated by anything...

sTHIS_IS_A_STRING_FINAL
iTHIS_IS_AN_INT_FINAL
connTHIS_IS_A_DB_CONNECTION_FINAL
hsrTHIS_IS_AN_HTTP_SERVLET_RESPONSE_FINAL

These descriptive prefixes are ridiculous, and too long. They're just used for emphasis.

BACK Import statements

Two things: Import everything, and never import package-dot-star.

Import everything

Do not create (non-java.lang) objects in your code, unless that object is explicitely imported at the top of the file. For example, never do this:

	the.package.TheObject to = new the.package.TheObject();

Instead:

	import the.package.TheObject;
//.....
	TheObject to = new TheObject();

An exception: When the current code imports two objects having the same name, but in different packages, the compile requires you prefix the object directly in the code. Such as java.util.Date and java.sql.Date

Never import package-dot-star.

Do not use import the.package.*, unless almost-every or truly-every class in that package is being used in your code. It is confusing to import an entire package when, actually, only one or two classes in that package are being used (but most are not).

BACK Parameter variable names

All parameter variable names should contain a single underscore. As a general rule, use the standards for non-parameter variable names, but replace the first capital letter with an underscore, and a lower-case version of that letter.

There should be a maximum of one underscore, which may not be the first or last character.

In the case of trivial variable names, explictely spell out the type, and separate the first and second letters (of a single-word type) or first and second words (of a multiple-word type) with an underscore. The first word/letter should start with lowercase, as well as the first word/letter following the underscore.

Examples:

Non-param var                   Param var
sTheString                      s_theString
acTheCharArray                  ac_theCharArray
s                               s_tring
i                               i_nt
hsr                             http_servletRequest