A side effect of the underscore naming convention is that it nicely resolves the problem of finding reasonable variable names for setter methods:

  void setName(String name)
  {
    name_ = name;
  }

An issue is whether the underscore should be added as a prefix or as a suffix. Both practices are commonly used, but the latter is recommended because it seem to best preserve the readability of the name.

It should be noted that scope identification in variables have been a controversial issue for quite some time. It seems, though, that this practice now is gaining acceptance and that it is becoming more and more common as a convention in the professional development community.

If for some reason this convention doesn't seem to fit it is a strong indication that the type name is badly chosen.

Non-generic variables have a role. These variables can often be named by combining role and type:

  Point  startingPoint, centerPoint;
  Name   loginName;

Using the is prefix solves a common problem of choosing bad boolean names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to chose more meaningful names.

Setter methods for boolean variables must have set prefix as in:

  void setFound(boolean isFound);

There are a few alternatives to the is prefix that fits better in some situations. These are has, can and should prefixes:

  boolean hasLicense();
  boolean canEvaluate();
  boolean shouldAbort = false;

Note that Oracle use num prefix in the core Java packages for such variables. This is probably meant as an abbreviation of number of, but as it looks more like number it makes the variable name strange and misleading. If "number of" is the preferred phrase, numberOf prefix can be used instead of just n. num prefix must not be used.

An elegant alternative is to prefix such variables with an i: iTable, iEmployee. This effectively makes them named iterators.

Variables named j, k etc. should be used for nested loops only.

cmd   instead of   command
comp  instead of   compute
cp    instead of   copy
e     instead of   exception
init  instead of   initialize
pt    instead of   point
etc.

Then there are domain specific phrases that are more naturally known through their acronym or abbreviations. These phrases should be kept abbreviated. Never write:

HypertextMarkupLanguage  instead of   html
CentralProcessingUnit    instead of   cpu
PriceEarningRatio        instead of   pe
etc.

An alternative to this approach is to put the constants inside an interface effectively prefixing their names with the name of the interface:

  interface Color
  {
    final int RED   = 1;
    final int GREEN = 2;
    final int BLUE  = 3;
  }

In general:

• Break after a comma.
• Break after an operator.
• Align the new line with the beginning of the expression on the previous line.

Appropriate tools should be used in order to always keep the import list minimal and up to date.

In addition, do-while loops are not needed. Any do-while loop can easily be rewritten into a while loop or a for loop. Reducing the number of constructs used enhance readbility.

Also, as in the last example above, it emphasize the type of the assigned variable (sum) at a point in the code where this might not be evident.

  if (condition) {
    statements;
  } else {
    statements;
  }

Note in particular:

• The opening /** on a separate line
• Subsequent * is aligned with the first one
• Space after each *
• Empty line between description and parameter section.
• Alignment of parameter descriptions.
• Punctuation behind each parameter description.
• No blank line bewteen the documentation block and the method/class.

Javadoc of class members can be specified on a single line as follows:

  /** Number of connections to this database */
  private int nConnections_;

It is a good practice to always document package private and private content in the same way.

If synchronization is an issue the members should identify by which lock it is protected.

There should be no reason to provide specific documentation for such methods. If the base class documentation is not sufficient it is a clear indication that the logic in the override should be in a different method.

• Prefer package classes to public classes.
• Prefer final classes to non-final classes.
• Prefer private inner classes to package classes if the class is local to one other class only.
• Prefer private static inner classes to private non-static inner classes.
• Prefer package methods to public methods.
• Prefer private methods to package methods.
• Prefer static private methods to private methods if the class members are not referenced, or it is natural to pass these as methods arguments.
• Prefer private members to protected members.

The general format of the overridden equals() method should follow the template above.

Always consider the alternative approach of implementing equals() which is to ensure that equal objects always are the same instances. This can be achieved by using factories that manage the pool of created objects.

The hashCode() method must be fast and should create its integer code from the hash codes of its immutable members and should ensure sufficient distribution of codes from the possible keys. This may involve convoluted mathematics including prime number factors etc. For the general client it is advised to simply use the logic provided by the JDK in the Objects.hash(...) method as shown above.

• Pass the exception on to the client. Do this if the exception cannot be adequately handled at this level, or the information provided by the exception is better handled by the client code:

              void method()
                throws SomeException
              {
                :
              }
            

• Catch the exception and pass on a different checked exception. Do this if the condition should be handled by the client code, but at a higher level of abstraction:

              try {
                :
              }
              catch (SomeException exception) {
                throw new OtherException(..., exception);
              }
            

• Handle the exception, typically by closing resources and logging:

              try {
                :
              }
              catch (SomeException exception) {
                :
                logger_.log(Level.WARNING, "Operation failed ... ", exception);
              }
            

• Ignore the exception. Do this only if it is certain the the exception will not be thrown, and document the fact with assert:

              try {
                :
              }
              catch (SomeException exception) {
                assert false : "This will never happen";
              }
            

Providing a good toString implementation simply makes classes much more pleasant to use, such as during debugging or with print outs.

If practical, a string representation of all the members of a class should be included in the toString method.

However convenient, the code must never rely on the exact format of this and if a specific string representation of a class content is used in the business logic, this logic must be provided by a different method than toString.

The reason is flexibility. toString should contain a scratch representation of the class content convenient for debugging or logging, and it should be possible to modify (for instance when the class changes) without any impact on the surrounding code.

According to the documentation rule above, always document the fact that null is never returned.

It is often argued that continue and break are variants of the infamous goto statement and that they therefore must be avoided. Likewise, it is argued that methods should contain a single point of return only. The examples above indicates that readability is greatly improved if instead the level of nesting is reduced as much as possible.