On Java Development

All things related to Java development, from the perspective of a caveman.

Java Standards and Best Practices

without comments


This post focuses on standards and best practices to employ while developing Java applications and presents topics such as naming conventions, screen design, source control, etc.

Love ‘em or hate ‘em, standards are a necessary part of program development. Without them developmental chaos will reign supreme and usually add up to time, effort and money wasted, none of which are desirable.

Successful software development is a long term activity and for this reason it is expected that the code base will be maintained by a succession of many different programmers over a period of many years. Without choosing a coding standard, you’ll likely end up with an informal one anyway as each developer of the organization fills the vacuum by evangelizing their own set of pet coding rules. Employing different rules, this often leads to applications behaving differently and means each have different training requirements for developers as well as the end users.

Standards will provide the following benefits.

  • Improved code maintainability.
  • Improved code quality leading to efficient and robust applications.
  • Improved development speed. Your developers don’t need to make all decisions starting from first principles.
  • Better teamwork. Don’t waste time with needless debates. Spend your creative energy on things that matter.
  • Developers can move to a different project or team and be productive sooner.
  • Better performance under pressure. Under stress, people fall back on what they’ve been trained to do.
  • Fewer bugs. Good standards should minimize common coding mistakes.
  • Shallower learning curve and useful training for new hires — if your standard mandates proven, well-known idioms and style from the programming mainstream.
  • Address audit requirements.

These are among some of the reasons why a coding standard will make application development over the long term easier, more productive and ensure the user’s experience is consistent across all applications.

The coding standard should be something developers learn from, want to follow, and want to contribute to; it should make their lives easier, not harder.

The coding standard should be a living document having a mechanism for evolving it and for dealing with the millions of lines of old code that are affected by changes to it.

The following topics are from “Java In A Nutshell”.

Naming and Capitalization Conventions
The following widely adopted naming conventions apply to packages, classes, methods, fields, and constants in Java. Because these conventions are almost universally followed and because they affect the public API of the classes you define, they should be followed carefully:

Ensure that your package names are unique by prefixing them with the inverted name of your Internet domain (e.g., com.davidflanagan.utils). All package names, or at least their unique prefixes, should be lowercase.

A class name should begin with a capital letter and be written in mixed case (e.g., String). If a class name consists of more than one word, each word should begin with a capital letter (e.g.,StringBuffer). If a class name, or one of the words of a class name, is an acronym, the acronym can be written in all capital letters (e.g., URL, HTMLParser). Since classes are designed to represent objects, you should choose class names that are nouns (e.g., Thread, Teapot, FormatConverter).

Interface names follow the same capitalization conventions as class names. When an interface is used to provide additional information about the classes that implement it, it is common to choose an interface name that is an adjective (e.g., Runnable, Cloneable, Serializable, DataInput). When an interface works more like an abstract superclass, use a name that is a noun (e.g., Document, FileNameMap, Collection). Looking to Oracle, now the owners of Java for a little more insight, they simply state the following;

Interface names should be capitalized like class names. Examples:

  • public interface RasterDelegate;
  • public interface Storing;

As usual, there will be exceptions. As an example, the following interface is named after a file on the iSeries.
public interface INGCLPDao extends GenericDao {

Implementing an Interface
Class that implement an interface should be named the same as the interface with the suffix of “Impl” appended to the name. Using the suffix conveys the idea that the class implements the named interface. Referring to the interface presented above, the name of the implementing class is –
public class INGCLPDaoImpl implements INGCLPDao {

A method name always begins with a lowercase letter. If the name contains more than one word,
every word after the first begins with a capital letter (e.g., insert(), insertObject(),
). Method names are typically chosen so that the first word is a verb.
Method names can be as long as is necessary to make their purpose clear, but choose succinct
names where possible.

Fields and constants
Nonconstant field names follow the same capitalization conventions as method names. If a field is a static final constant, it should be written in uppercase. If the name of a constant includes more than one word, the words should be separated with underscores (e.g., MAX_VALUE). A field name should be chosen to best describe the purpose of the field or the value it holds.

The names of method parameters appear in the documentation for a method, so you should choose
names that make the purpose of the parameters as clear as possible. Try to keep parameter names to a single word and use them consistently. For example, if a WidgetProcessor class defines many methods that accept a Widget object as the first parameter, name this parameter widget or even w in each method.

Local variables
Local variable names are an implementation detail and never visible outside your class.
Nevertheless, choosing good names makes your code easier to read, understand, and maintain.
Variables are typically named following the same conventions as methods and fields.

Best Practices

Hardcoded filenames
A portable program contains no hardcoded file or directory names. This is because different platforms have significantly different filesystem organizations and use different directory separator characters. If you need to work with a file or directory, have the user specify the filename, or at least the base directory beneath which the file can be found. This specification can be done at runtime, in a configuration file, or as a command-line argument to the program. When concatenating a file or directory name to a directory name, use the File() constructor or the File.separator constant.

Line separators
Different systems use different characters or sequences of characters as line separators. Do not hardcode “\n”, “\r”, or “\r\n” as the line separator in your program. Instead, use the println() method of PrintStream or PrintWriter, which automatically terminates a line with the line separator appropriate for the platform, or use the value of the line.separator system property.

Java Documentation Comments

Most ordinary comments within Java code explain the implementation details of that code. In contrast, the Java language specification defines a special type of comment known as a doc comment that serves to document the API of your code. A doc comment is an ordinary multiline comment that begins with /** (instead of the usual /*) and ends with */. A doc comment appears immediately before a class, interface, method, or field definition and contains documentation for that class, interface, method, or field. The documentation can include simple HTML formatting tags and other special keywords that provide additional information. Doc comments are ignored by the compiler, but they can be extracted and automatically turned into online HTML documentation by the javadoc program. (See Chapter 8, “Java Development Tools”, for more information about javadoc.) Here is an example class that contains appropriate doc comments:

Using the equals() method

As the name implies, the equals() method is often used to determine equality between two string objects. When comparing such objects to a literal string value and the object turns out to contain a null, the test will throw an exception. This is because Java is attempting to execute the equals() method for the null object.

The example below compares such an object against a literal. if the object runtimeEnvironment is null, an exception is thrown, which is a time-consuming process for the machine.

Instead, code the test like this;

The outcome of the test will either be true or false. Nothing less. There is now no way for the test to throw an exception when the runtimeEnvironment object contains a null.

Written by admin

January 21st, 2014 at 6:01 pm

Posted in Standards

Tagged with

Leave a Reply

You must be logged in to post a comment.