Rinehart on Java Coding Conventions

Introduction

Is this merely one man's opinion? Sure. But that one man has written Java since Java 1.0. He's written in other programming languages since 1965. Hopefully, he's learned a bit along the way. At the very least, he's earned the right to be crotchety.

Java Coding Conventions

© 2005, Martin Rinehart
from www.MartinRinehart.com

Introduction

Why So Many Other Conventions?

In alphabetical order, the non-Sun conventions are:

• Scott W. Ambler, coauthor of The Elements of Java Style, publishes his own conventions at Ambler.
• The Infospheres team at CalTech (editors Joseph Kiniry and Daniel M. Zimmerman) posts its conventions at Caltech.
• Geotechnical Software Services, a Norwegian software company has an excellent, recent convention set available at Geosoft.
• New England Java User Group's active conventions committee (Doug Chamberlin, editor) has published a short book at NEJUG.

References to Conventions

Ambler numbers sections (6 Classes, Interfaces, ... — 6.1 Classes — 6.1.1 Class Visibility). A reference to class visibility in Ambler is [Ambler 6.1.1].

Caltech does not provide a comparable navigation feature but it does provide a convenient, hyper-linked table of contents at the top. The reference to a naming convention will be [Caltech Naming Conventions].

Geosoft's organization is similar to Sun and Ambler (6 Layout and Comments — 6.1 Layout) but it numbers each convention consecutively. The first convention under 6.1 is "58 Basic indentation ...". This will be referred to as [Geosoft 58].

The New England Java User Group proposes Standards (must be followed — STD), Styles (should be followed, but some room for decision — STY) and Conventions (no recommendation, but make up your own mind and stick to your decision — CON). Style 13, Ternary Statement Usage, will be referred to as [NEJUG STY-13].

I have tried to be complete. For example, 2.2 Package Comments includes references to Ambler and to Caltech. This implies that the other three conventions do not address this issue.

Comment Types

Organization

1. General
2. Package
3. Compilation Unit
4. Type (Class and Interface)
5. Class-Wide Data
6. Methods
7. Statements Within Methods

This paper doesn't cover "good advice" conventions that programmers using any language should know (choose meaningful variable names, for example). This paper also excludes requirements (the compiler reads files with a ".java" suffix). It focuses on choices the programmer needs to make. This document is not a substitute for the referenced documents — they include many useful examples and discussions of the options. The goal here is a terse summary that lets you see where the standards agree, disagree and are silent.

1 General

  1.1 Conventions About Conventions

  1.2 Language

  1.3 Implementation Comments

  1.4 Acronyms

  1.5 Other

[Caltech Structure] recommends that javadoc comments end with **/. The other standards do not specifically address this but all their examples show javadoc ending with */.

No convention specifies that javadoc comments have empty top and bottom lines, but all examples are done this way: /** * doc comment here */

Pet peeve. One of the resources that is still scarce is vertical space. My code editor shows about 60 lines. The more code I can see at once, the happier I am. Therefore, I don't waste vertical space. My standard is: /** doc comment here */

Contents 1 General 2 Package   2.1 Package Names   2.2 Package Comments 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

2 Package

  2.1 Package Names

  2.2 Package Comments

Contents 1 General 2 Package 3 Compilation Unit   3.1 Compilation Unit Names   3.2 Compilation Unit Comments   3.3 Compilation Unit Format     3.3.1 Compilation Unit Sections     3.3.2 Package and Import Statements     3.3.3 Line Length and Breaks     3.3.4 Indentation   3.4 Compilation Unit Other 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

3 Compilation Unit

  3.1 Compilation Unit Names

  3.2 Compilation Unit Comments

[Sun 3] also suggests an optional comment identifying the sections of the file.

Embedded HTML tags in comments are specified by [Caltech Documentation] in an effort to make intra-file navigation as simple as Javadoc navigation. (Caltech does not claim to have solved the problem, only to be working on a solution.)

  3.3 Compilation Unit Format

    3.3.1 Compilation Unit Sections

    3.3.2 Package and Import Statements

The imports should use "*" (as in java.awt.*) according to [Ambler 7.2], and shouldn't use "*", according to [Ambler 7.2.1] and [Caltech Structure]. [NEJUG STY-3] considers both positions and concludes that "*" should be used for standard (Sun) classes but not for your own classes. The order of imports is java.xxx first, javax.xxx next and then others alphabetically according to [Caltech Structure] and [Geosoft 36]. [NEJUG STY-2] suggests that third-party packages be imported between Sun's and your own. [Sun 3.1.2] only says that imports follow the package statement.

A hot-key in my IDE searches my code and then neatly lays out imports for exactly the types that need importing, and no more. Since my IDE can be downloaded without cost, this rather exacting (and formerly time-consuming) standard should be universal.

    3.3.3 Line Length and Breaks

Over-length lines must be broken. The broken part is indented ([Sun 4.1], [Ambler 2.4.3], [Geosoft 34] and [NEJUG STY-8]). Breaks are after commas and operators (except Sun, which specifies breaking before binary operators). Geosoft and NEJUG strongly disagree, stating that the "broken" condition of the line should be made as obvious as possible — which means the break is after the operator.

Re breaking after binary operators, Geosoft and NEJUG are right. When lines are broken, the parts should be the largest possible lexical units. For example: Preferred Inferior var_name = complete + expression; var_name = broken + expression;

    3.3.4 Indentation

  3.4 Compilation Unit Other

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface)   4.1 Type Names   4.2 Type Comments   4.3 Type Format     4.3.1 Format of the Type Statement     4.3.2 Items Within the Type     4.3.3 Order of Methods   4.4 Type Other 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

4 Type (Class and Interface)

  4.1 Type Names

[Caltech Naming Conventions] also suggests starting with "Abstract" and ending with "Factory" and "Exception" for the respective class types, and ending with "Impl" for an implementation. [Geosoft 27, 28] specifies starting with "Default" and ending with "Exception" for those types.

[Ambler 1.3] recommends against names longer than 15 characters.

  4.2 Type Comments

An implementation comment should follow the type statement, per [Sun 5.2].

// end of class Xxx may follow the closing brace, per [Caltech Structure].

An // end of ... comment should follow every closing brace except those that are within a few lines of their opening mate. Comments are free. Lack of comments can be expensive.

  4.3 Type Format

    4.3.1 Format of the Type Statement

type name extends superclassname
  implements interface list

type name
    extends superclassname
    implements interface // single interface

type name
    extends superclassname
    implements
        interface1,
        interface2,
        ...

    4.3.2 Items Within the Type

No convention mentions the main() method. This is a problem for me as I almost always write a main() for testing and comment it out after testing is completed. Once commented out, it is invisible to my IDE so I cannot navigate to it — or I couldn't if I didn't know that it immediately precedes the first constructor.

Note that this editorial comment was inserted in the original. I thought it important enough to break my own rules, and have not changed my opinion.

    4.3.3 Order of Methods

By a single blank line [Sun 6.4], [Sun 8.1] By two blank lines [NEJUG STY-28], [Caltech Structure] By 3 to 5 blank lines [Geosoft 73]

Have you ever heard a programmer complain that too many lines of code were visible at once on his monitor? While the cost of many resources approaches zero these days, vertical real estate is still scarce. Use a single line. The javadoc is significantly distinguishing.

The open brace is on the same line as the type statement [Sun 6.4], or it is on the next line [Geosoft 59]. The close brace is not indented, on a line by itself [Sun 6.4].

  4.4 Type Other

"Facade" classes should be public, others should use package visibility per [Ambler 6.1.1]. Use of public and protected visibility should be minimized, per [Ambler 6.1.5].

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data   5.1 Class-Wide Data Names   5.2 Class-Wide Data Comments   5.3 Class-Wide Data Format   5.4 Class-Wide Data Other 6 Methods 7 Statements Within Methods Conventions Map

5 Class-Wide Data

Note: More precisely, but possibly confusingly, these conventions are type-wide — class and interface — not just class-wide.

  5.1 Class-Wide Data Names

Use lowerAndUpper convention [Sun 9.5], [Ambler 1.3, 3.1.1], [Caltech Naming Conventions], [Geosoft 4, 11], [NEJUG STD-3]. Use UPPER_AND_UNDERSCORE convention for constants. [Sun 9.6], Ambler 3.1.3], [Caltech Naming Conventions], [Geosoft 5], [NEJUG STD-5].

Agreed with all, plus use Mixed_And_Underscores for statics.

Avoid long names (over 15 chars) and names differing only in case [Ambler 1.3].

Name widgets with a postfix type: okButton, nameField ([Ambler 3.1.2] and [Geosoft 18]).

Collections: use plural noun: customers, products ([Ambler 3.1.4] and [Geosoft 19]).

Private class variables should have an underscore suffix (name_) [Geosoft 8]. Generic variables should have the same name as their type (Database database) [Geosoft 9]. Use an "n" prefix for number of (nLines) [Geosoft 20]. Use a "No" suffix for entity number (employeeNo) [Geosoft 21]. Use complement names (first/last, next/previous) [Geosoft 23]. Don't abbreviate (ActionEvent event) [Geosoft 24]. Associated constants should share a prefix (COLOR_RED, COLOR_BLUE) [Geosoft 26].

  5.2 Class-Wide Data Comments

Provide javadoc ([Sun 5.2], [Ambler 1.4.1], [Caltech Structure]). Document: description, invariants, examples, concurrency, visibility (if not private) [Ambler 3.3].

Collections of a single type should have an EOL comment (ArrayList coins; // of Coin) [Geosoft 80].

  5.3 Class-Wide Data Format

One declaration per line [Sun 6.1]. All data before methods, statics before (or after) instance [Caltech Structure], or variables and methods together in order of visibility (public, protected, package, private) [Ambler 6.1.4.2].

Offset groups with comments [Caltech Structure].

Left-align variable names in declarations ([Sun 6.1], [Geosoft 74]). Example:

    Widget[]    widgets;
    int         nWidgets;

  5.4 Class-Wide Data Other

Per [Sun 10.1] and [Geosoft 42], don't use "public" access unless you really have a struct (a class with fields but no methods manipulating those fields). More strictly, use minimal visibility per [Ambler 2.2] and [NEJUG CON-7], which means all fields should be private, accessed through getters/setters per [Ambler 3.2, 3.4] and [NEJUG CON-8].

Initialize fields in declarations or in a constructor, but not both ([NEJUG STY-17]). Define constants in an interface ([NEJUG CON-13]).

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods   6.1 Method Names   6.2 Method Comments   6.3 Method Format   6.4 Method Other 7 Statements Within Methods Conventions Map

6 Methods

  6.1 Method Names

Method names should be verbs ([Sun 9.4], [Ambler 2.1], [Geosoft 6], [NEJUG STD-3]) and they should use the lowerAndUpper convention [Sun 9.4], [Ambler 1.3, 2.1], [Caltech Naming Conventions], [Geosoft 6], [NEJUG STD-3]. Getters and setters should use bean convention names — getXxx(), isXxx() and setXxx() — per [Ambler 2.1.1, 3.4.1], [Caltech Naming Conventions], [Geosoft 13], [NEJUG STY-26].

Converter methods start with "to" (toDegrees()) [Caltech Naming Conventions].

Geosoft has much more to say about method names. The name of the object should not be included (line.getLength(), not line.getLineLength()) [Geosoft 12]. If the method computes something, use "compute" (computeAverage() ) [Geosoft 15]. Use "find" for lookup (findNearestVertex() ) [Geosoft 16]. Use "initialize" (printer.initializeFontSet() ) [Geosoft 17]. Use complement names (get/set, add/remove) [Geosoft 23]. Don't abbreviate (computeAverage()) [Geosoft 24]. Don't negate booleans (isFound(), not isNotFound() ) [Geosoft 25]. Methods returning data should be named after what they return; void methods after what they do [Geosoft 29].

  6.2 Method Comments

Provide all public methods with javadoc [Sun 5.2], [Ambler 1.4.1], [Caltech Structure], [NEJUG STD-6]. All public and protected methods need javadoc [Geosoft 81]. The method comment should cover what/why method does, parameters, returns, bugs, exceptions, visibility decisions, changes to object, code change history, examples, pre/post conditions and concurrency [Ambler 2.3.3].

Implementation comments should precede methods [Sun 5.1]. Implementation comments should explain what and why [NEJUG CON-11]. Implementation comments cover control structure, what/why, local variables, difficult or complex code, and processing order. [Ambler 2.3.3].

For non-trivial methods, document the closing brace [Ambler 2.3.3]:

public type whateverMethod(parameters) {
...
... non-trivial code here
...
} // end of whateverMethod()

In Javadoc, parameters should have purpose, restrictions/preconditions, and examples, if required [Ambler 5.2].

  6.3 Method Format

Use one blank line between the javadoc comment and the method's code, per [Caltech Structure]. Others do not show this blank line in their examples.

Agree with others. Do not waste vertical space.

[Geosoft 38] Specifies the order for the modifiers to be access, static, abstract, synchronized, <unusual>, final, native.

It is agreed that no space separates the name and open parenthesis [Sun 6.4], [NEJUG STD-3].

The parameters are all on one line, or each can be on its own line, per [Caltech Structure].

They must have really huge monitors at Caltech.

There is no agreement on the location of the open brace. It goes on the same line as the name [Sun 6.4] or on the next line [Caltech Structure], [Geosoft 59].

Both styles place the close brace on a line by itself, indented to the start of the name line — [Sun 6.4], [Caltech Structure].

[Sun 6.4] specifies "{}" for an empty method.

[Geosoft 61] specifies this method format:

public void someMethod()
  throws SomeException
{
...
}

  6.4 Method Other

Access static methods by ClassName.method(), not by an instance variable ([Sun 10.2], [Geosoft 57] and [NEJUG CON-15].

Use minimal visibility [Ambler 2.2]. Getters/setters should be protected, if possible [Ambler 3.4.3].

Constructors should leave objects in a stable state [NEJUG CON-2]. Methods should accomplish a single task [NEJUG CON-3].

In a group of size recommendations, NEJUG stresses that the exact number should be set to meet the organization's needs. Limit methods to 30 (or other) lines [NEJUG CON-4]. Limit number of methods to 30 (or other) [NEJUG CON-6]. Limit number of parameters to 5 (or other) [NEJUG CON-9]. Minimize public methods and variables [NEJUG CON-7].

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods   7.1 Variable Names   7.2 Statement Comments   7.3 Statement Formats     7.3.1 Agreed Statement Conventions     7.3.2 Formatting the Ternary Expression     7.3.3 Declarations Formats     7.3.4 Block Statement Formats     7.3.5 Switch Formats     7.3.6 Try/Catch/Finally Formats     7.3.7 Miscellaneous Formatting   7.4 Statement Other Conventions Map

7 Statements Within Methods

  7.1 Variable Names

There are few disagreements about variable names. They should use the lowerAndUppercase convention ([Sun 9.5], [Ambler 1.3, 3.1.1], [Geosoft 4, 11], [NEJUG STD-4]) and a lower-level name (in a code block) should not hide a higer-level (outer block or class-wide) name ([Sun 6.1], [Ambler 3.1.5], [NEJUG STD-9]).

Please add Mixed_And_Underscore for privates.

Single-letter names are OK for "throwaway" variables (very limited scope) such as loop counters [Sun 9.5], [Ambler 4.1.2], [Geosoft 11]. Just "e" is OK for an Exception [Ambler 4.1.3] and "i", "j", "k" can name iterators (Iterator i = ...) [Geosoft 22].

[Ambler 4.1.1] suggests xxxStream for streams and later, [Ambler 5.1] suggests using the same name conventions for parameters as for other variables.

[Geosoft 24] warns us not to abbreviate (ActionEvent event).

Single-letter names are preferred when the scope is limited. ActionEvent e tells you that the scope of "e" is very short. Use "event" if the scope is not limited.

  7.2 Statement Comments

Most conventions stress good coding practices—if your code needs extensive comments considering re-writing as an alternative to commenting. Of course, comments are desired and sometimes required, The non-disputed in-method conventions are:
• Leading comment blocks are preferred over numerous (code obscuring) comments [NEJUG STY-20]
• A blank line should precede an implementation block comment (including a single-line block comment) [Sun 8.1], [NEJUG STY-19, 28]
• Single-line block comments should be indented to match following code [Sun 5.1.2], [NEJUG STY-19]

After these, there is considerable disagreement on the subject of block comments and EOL comments. Some conventions avoid the use of block comments for commentary, as they make it harder to use block comments to comment out code. Others use EOL comments to comment out code as they make the commented-out nature stand out. These are the positions:

[Sun 5.1.3] uses block comments for trailing, single-line notes EOL comments also used for trailing comments and to comment out code blocks, but not for comment blocks [Sun 5.1.4]. EOL comments are used to comment out code blocks [NEJUG STY-18]. EOL comments are used for comment blocks, block comments are used to comment out code blocks [Ambler 1.4.1], [Caltech Documentation], [Geosoft 78].

Some of these are too idiosyncratic for standards. Use EOL comments when you want an EOL comment. Use block-comment delimiters when you have a block comment.

Finally, there are these additional conventions. Use XXX in a comment if the code is bogus, but it works; use FIXME if the code is bogus and broken [Sun 10.5.4]. You should document closing braces in long blocks ([Caltech Structure] and [NEJUG CON-17]) and you should comment variable declarations, including the addition of new variables, per [NEJUG STY-21].

  7.3 Statement Formats

    7.3.1 Agreed Statement Conventions

A few conventions are generally agreed. There should be just one statement per line ([Sun 7.1], [Ambler 2.4.6, 4.2], [NEJUG STY-21, 23]). The one disagreement comes from [Geosoft 43] which allows related variables of a single type to be declared together: (float x, y, z;). The use of assignment within another expression is discouraged by [Sun 10.4] and [Geosoft 53]

Blank lines should be used to "paragraph" — group related lines together — the code ([Sun 8.1], [Ambler 2.4.2, 2.4.4], [Geosoft 72], [NEJUG STY-28]). Similarly, a blank line can separate variable declarations from the start of the code ([Sun 8.1] and [NEJUG STY-28]).

The standards are nearly unanimous in stressing the use of parentheses as superior to depending on precedence rules ([Sun 10.5.1], [Ambler 2.4.7], [Caltech Structure], [NEJUG CON-16]).

We should use a single space:

• between any keyword and an open parenthesis ([Sun 8.2], [Caltech Structure]and [NEJUG CON-14]
• after the commas in a parameter list ([Sun 8.2], [NEJUG CON-14])
• after the semicolons in a "for" loop control expression ([Sun 8.2])
• on either side of a binary operator, but not between a unary operator and its operand ([Sun 8.2], [Caltech Structure], [NEJUG CON-14])
• after a cast ([Sun 8.2]

    7.3.2 Formatting the Ternary Expression

[Sun 4.2] suggest three ways to format the ternary: 1 a = (expr) ? b : c; 2 a = (expr) ? b : c; 3 a = (expr) ? b : c; Only the first of these meets Geosoft's and NEJUG's concern for having the "brokenness" of the line be obvious (see 3.3.3 above re breaking lines in compilation units). Additionally [NEJUG STY-13] suggests that we use only simple, never nested, ternary expressions.

Sun's second and third forms are strange—a standard that no one has adopted. I suspect that most code would be more readable if the ternary were never used. I'd ban it except for use in formatting output. I oppose capital punishment but I might be persuaded to make an exception for programmers who nest ternaries.

[Sun 10.5.3] specifies that the ternary's condition is always parenthesized.

    7.3.3 Declarations Formats

All declarations should be at the beginning of blocks (or, for loop control variables, in "for" statements) if you agree with [Sun 6.3] and [NEJUG STY-22] or the declarations should be immediately before the variables' use, if you agree with [Ambler 4.2]. Possibly splitting the difference, [Geosoft 40, 45] tells us to declare local variables in the smallest possible scope.

Programs should read like English. Paragraphs should contain complete thoughts. If a variable can be created, used and disposed of within a "paragraph," that's the best treatment. If a variable has a wider scope, declare it at the beginning of its scope.

All declarations should be at the beginning of blocks (or, for loop control variables, in "for" statements) if you agree with [Sun 6.3] and [NEJUG STY-22] or the declarations should be immediately before the variables' use, if you agree with [Ambler 4.2]. Possibly splitting the difference, [Geosoft 40, 45] tells us to declare local variables in the smallest possible scope.

[Geosoft 47] tells us to initialize loop variables just before the loop:

    boolean isDone=false;
    while (!isDone)
    {
    ...
    }

Similarly [Geosoft 46] tells us to never include initialization or update for anything except the loop control variables in a "for" statement. Other initialization should be done prior to the "for" and updates should be in the block statement body.

[Sun 6.2] and [Geosoft 40] specify initialization of local variables where declared (if possible).

[NEJUG STY-16] agrees but only if the initial values are not the default values as this adds to the code size and is redundant. Sun's example declarations show ints being initialized to zero.

NEJUG was correct that int i = 0; created more code than the logically equivalent int i;. That is an implementation bug and one should assume that sooner or later it will be fixed. If initialization is required, it should be coded explicitly. (Assume that the code maintainer uses multiple languages, and Java is not the primary one.)

    7.3.4 Block Statement Formats

The same dispute about the placement of opening braces exists within the method as it does for the method itself. This is the style from [Sun 7.2]:

if (expr) { statement[s]; } This is the preference of [Geosoft 59]: if (expr) { statement[s]; }

Silly discussion that dates back to the dawn of C. Pick a style and stick to it.

This is the standard from [Sun 7.4]:

    if (expr) {
        statement[s]
    } else {
        statement[s]
    }

[Geosoft 62] says we should always use a new line for each "else."

We should always use braces [Sun 7.2], [Caltech Structure], [NEJUG STY-24] or we can skip them for a single-line statement [Geosoft 69]. If you use the single-line statement, it should be on a separate line, per [Geosoft 52].

if (expr) statement;

I am almost in the "always use braces" camp, but with one important exception. I use if (expr) statement; when the logic is such that one and only one statement can follow that "if." The absence of braces emphasizes the fact that we have exactly one statement if the expression is true.

In [NEJUG STY-11] we are asked to indent controlled statement blocks (if, for, while, etc.) one level. [NEJUG STY-12] declares neutrality on the opening brace same line or next line debate.

If necessary to break a conditional, indent the broken part(s) 8 spaces and the following block statement just 4 spaces ([Sun 4.2]).

Way too dogmatic. I'll be dogmatic about just one thing: breaks should be as readable as possible. Lining things up often helps: if ( (this comp that) && (some other comp) ) {

An empty block after a "for" statement should be a semi-colon on the same line as the "for" [Sun 7.5] or it should be a semi-colon placed on the following line [Geosoft 63, 64]. This also applies to "while" loops ([Sun 7.5]).

    7.3.5 Switch Formats

Per [Sun 7.8] the general form of a switch statement is:

    switch (condition) {
        case A:
            statements;
            break;
        case B:
            statements;
            break;
        default:
            statements;
            break;
    }

If you wish execution to fall through from case A into case B, replace the break with "/* falls through*/" ([Sun 7.8]) or with "// falls through" ([Geosoft 67]) or never fall through — always include the "break" ([NEJUG STY-14]). [NEJUG STY-15] requests that the "default" case always be included.

If the "falls through" concept had not been part of C, the world would have been a less buggy place. Never fall through. Repeat a tiny bit of code: // BUG SOURCE // straightforward case A: case A: func1(); func1(); case B: func2(); func2(); break; break; case B: func2(); break;

Additionally [Geosoft 70] specifies a single space before the colon (case A :).

    7.3.6 Try/Catch/Finally Formats

[Sun 7.9] specifies this format:

    try {
        statements;
    } catch (ExceptionClass e) {
        statements;
    } finally {
        statements;
    }

As always, [Geosoft 68] leaves the closing braces on lines of their own.

    7.3.7 Miscellaneous Formatting

[Ambler 2.5.2] suggests putting constants on left side of comparisons: if ( 1 < x ) ... .

Only if this improves clarity.

[Geosoft 44] declares arrays with brackets next to type(int[] foo, not int foo[]).

[Geosoft 75] asks for horizontal alignment to be used to enhance readability:

   aWidget.      addMouseListener();
   theWidget.    addMouseListener();
   anotherWidget.addMouseListener();

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

  7.4 Statement Other

We should use named constants, not numeric constants except for 1, 0 and -1 in loop control, per [Sun 10.3] and [NEJUG STY-29]. [Geosoft 54] concurs but omits the "-1".

Return boolean (or ternary) rather than use multiple returns within an if/else construct ([Sun 10.5.2]).

I agree that multiple returns within an if/else is a bad idea. Returning a ternary is almost as bad. When you tell your debugger, "next step, please" you want just one step. You do not want it to perform some logic, then return a value (presumably problematic) and smile at you from the same point where you first noticed the problem. Consider the testability of these: // UNDEBUGGABLE return expr1 ? expr2 : expr3; // easily debugged type ret; if ( expr1 ) { ret = expr2; } else { ret = expr3; } return ret; With the latter, you can step through with your debugger and see which branch you are taking and you can examine the value before it's returned. Old-timers like me will slip debugging output statements into both conditional branches—another thing that can't be done with Sun's solution.

Document local variables with an EOL comment ([Ambler 4.2]). Also, never reuse local variables ([Ambler 4.2] and [Geosoft 41]).

Additional conventions from Geosoft are:

• Always cast (float f = (float) i) [Geosoft 39]
• Avoid do/while loops [Geosoft 48]
• Avoid break and continue [Geosoft 49]
• Use temporary booleans to simplify complex conditionals [Geosoft 50]
• Normal case in "if" part, exception in "else" part [Geosoft 51]
• Use a decimal point and at least one decimal for floats [Geosoft 55]
• Use at least one digit to the left of the decimal point for floats [Geosoft 56]

Finally, [NEJUG CON-1] recommends protecting code with try/finally blocks and [NEJUG CON-12] recommends against nesting conditions more than four deep.

I recommend extreme skepticism when nesting of anything gets four deep. You can always reduce nesting by creating temporary variables for the deepest calculations or comparisons, then using these variables for the less deep calculations and comparisons. This normally improves readability. It also has considerable advantages when it's time to debug those complex expressions.

---

Appendix - Convention Coverage Map

Topic	Sun	Ambler	Caltech	Geosoft	NEJUG
1 General
1.1 Conventions About Conventions		1.2, 1.5		1
1.2 Language		1.4		10, 77
1.3 Implementation Comments	5, 5.1	1.4			STD-7
1.4 Acronyms		1.3			STD-2
1.5 Other			Structure		STD-8, STY-27, CON-10, 19-21
2 Package
2.1 Package Names	3.1.2, 9.1	6.3.1	Naming Conventions	2	STD 1
2.2 Package Comments		6.3.2	Structure
3 Compilation Unit
3.1 Compilation Unit Names
3.2 Compilation Unit Comments	3, 3.1.1	6.4.2	Documentation, Structure
3.3 Compilation Unit Format	3.1		Structure	30
3.3.1 Compilation Unit Sections	3, 3.1.1, 8.1				STY-1,28
3.3.2 Package and Import Statements	3.1.2	7.2, 7.2.1	Structure	36	STY-2,3
3.3.3 Line Length and Breaks	4.1	2.4.3		34	STY-8
3.3.4 Indentation	4	2.4.2	Structure	33, 58	STY-9,10
3.4 Compilation Unit Other	3				CON-5
4 Type (Class and Interface)
4.1 Type Names	9.2	1.3, 6.1.2, 6.2.1	Naming Conventions	3, 27-8	STD-2
4.2 Type Comments	5.2	1.4.1, 6.1.3, 6.2.2	Structure	37	STD-6
4.3 Type Format
4.3.1 Format of the Type Statement				60
4.3.2 Items Within the Type	3.1.3			37	STY-4,5
4.3.3 Order of Methods	3.1.3, 6.4, 8.1	6.1.4.2	Structure	59, 73	STY-5,28
4.4 Type Other		6.1.1, 6.1.5
5 Class-Wide Data
5.1 Class-Wide Data Names	9.5, 9.6	1.3, 3.1.1-4	Naming Conventions	4, 5, 8-9, 11, 18-21, 23-4, 26	STD-3,5
5.2 Class-Wide Data Comments	5.2	1.4.1	Structure	80
5.3 Class-Wide Data Format	6.1	6.1.4.2	Structure	74
5.4 Class-Wide Data Other	10.1	2.2, 3.2, 3.4		42	CON-7,8,13 STY-17
6 Methods
6.1 Method Names	9.4	1.3, 2.1, 2.1.1, 3.4.1	Naming Conventions	6, 12-3, 15-7, 23-5, 29	STD-3, STY-26
6.2 Method Comments	5.1-2	1.4.1, 2.3.3, 5.2	Structure	81	STD-6, CON-11
6.3 Method Format	6.4		Structure	38, 59, 61	STD-3
6.4 Method Other	10.2	2.2, 3.4.3		57	CON-2,4,6,7,9,15
7 Statements Within Methods
7.1 Variable Names	6.1, 9.5	1.3, 3.1.1, 3.1.5, 4.1.1-3, 5.1		4, 11, 22, 24	STD-4,9
7.2 Statement Comments	5.1.2-4, 8.1, 10.5.4	1.4.1	Documentation, Structure	78	STY-18-21,28 CON-17
7.3 Statement Formats
7.3.1 Agreed Statement Conventions	7.1, 8.1-2, 10.4, 10.5.1	2.4.2, 2.4.4, 2.4.6-7, 4.2	Structure	43, 53, 72	STY-21,23,28 CON-14
7.3.2 Formatting the Ternary Expression	4.2, 10.5.3				STY-13
7.3.3 Declarations Formats	6.2-3	4.2		40, 45-7	STY-16,22
7.3.4 Block Statement Formats	4.2, 7.2, 7.4-5		Structure	52, 59, 62-4, 69	STY-11-2,24
7.3.5 Switch Formats	7.8			67, 70	STY-14-5
7.3.6 Try/Catch/Finally Formats	7.9			68
7.3.7 Miscellaneous Formatting		2.5.2		44, 75
7.4 Statement Other	10.3, 10.5.2	4.2		39, 41, 48-51, 54-6	STY-29 CON-1,12

---



Back to Articles