The following are standards for Partner Java source code style - formatting, commenting, etc.
These standards have been updated for the version 5 codebase. There are minor differences between this and version 4 style. Either version 4 or version 5 style may be used in version 4 code, but version 5 code should use the style standards described here.
In the interest of simplicity and ease of use, basic formatting (brace placement, indention, etc.) is defined as the that used by the default settings of the Eclipse Java IDE. In most cases the Eclipse menu option Source/Format will correct a given Java file to this standards’ formatting conventions.
There are four major types of comments used commonly in Partner Java files:
JavaDoc comments are according to the Java standard. They appear before declaration elements for things like classes, properties, and methods.
Here is a document on JavaDoc style: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
JavaDoc specifies a number of special variables, prefixed with an @ sign (e.g. @author). In general these tend to be put in but not maintained or filled in carefully, so omit them unless you are planning on filling them in carefully.
Section markers help divide up the parts of a class into sections and facilitate searching and similar organization. Java doesn’t have a standard for this, but e.g. in Objective-C there is the “#pragma mark” directive that does something similar.
Level-of-intent descriptions are often the most useful (and often most lacking) type of documentation. This is a longish description of the algorithm, task, design, or approach before a large or complex piece of code.
Inline comments are generally the most common and aren’t necessarily the most useful type of documentation. Good naming standards and clear coding techniques eliminate most of the the need for describing the low-level details of the code outside the code itself.
Assume that the reader is reasonably fluent in Java, and only use inline comments to break up code into sections, flag issues (see Marker Terms), or to explain tricky bits.
This is true in general - don’t just fill in comments with a repetition or rewrite of the method name or similar words that are obvious from inspecting the code declarations. That’s just busy work. Best to leave the comment out entirely. Disable automated comment generation if you aren’t going to thoughtfully modify the results; it just adds bulk to the file and makes it harder to dig through without improving the documentation.
Class and interface declarations have some requirements beyond JavaDoc standard.
The first line should be a one-sentence description of the class or interface.
Additional description should be given in paragraphs following, separated only by HTML <p>.
After this, a copyright notice must be placed. This has the following format:
Copyright 2010-2013 Partner Software, Inc.
This should be maintained whenever the code is changed; e.g. it starts with just the year the code was begun, and when it is modified henceforth it should be updated. It does not need to be automatically modified (though that’s a consideration if someone wants to write an automated tool...). There are legal reasons for this descriptor, but it is also helpful to know how old the code is. Seeing code marked with a 1998 copyright - and no updated end year - should give anyone qualms.
After the copyright, author markers are placed. These correspond to automated tools (by JavaDoc and SVN, currently) and have the following format:
@author Paul Reavis
Add more @authors to reflect who did substantial work on it. This is both informational and should be something of a badge of pride... or not.
Here is a full example:
/**
* A widget that does foo.
* <p>
* Doing foo is a critical function for the Bar application. This implements the foo feature in the Widget framework.
* <p>
* Copyright 2010-2012 Partner Software, Inc.
* @author Paul Reavis
*/
public class FooWidget extends Widget implements Foo {
Section markers have a specific format as follows:
//-- whatnot --//
The following standard sections are used when appropriate for a class or interface:
TODO consider the @category javadoc notation supported by Eclipse.
Certain terms are used to mark specific issues or categorize comments. Using standard terms facilitates automated searching.
They are as follows: