Jmol Coding Standard

Jmol Coding Standard

Professional software developers know that it is important to maintain a consistent coding style. Having a consistent style with regular idioms makes it easier to spot problems.

More importantly, it allows you to read the code without distractions.

It is particularly important on group projects where more than one person is looking at the. Understanding code is difficult enough , without throwing-in lots of distractions caused by inconsistent punctuation and indentation.

Everyone agrees that it is demonstrably better to have a consistent coding style within a project. This far outweighs any personal preferences that an individual may have.

When you write Linux kernel code you use one style. When you write Jmol code you use another.

• Your text editor should indent and reindent automatically for you. If you don't know how to enable this feature in your text editor then learn how to enable it. If your text editor cannot do this then get another text editor.
• Indentation level should be two spaces.

class Foo {
  int someClassVariable;

  Foo(int evenOrOdd) {
    someClassVariable = 99;
  }

  ...
}

• Space characters should be used instead of tabs.
• Assignment and arithmetic operators generally contain spaces on both sides.

a = b + c;

• You are allowed to eliminate the spaces within expressions in order to make operator precedence more clear.

int cSquared = a*a + b*b;

• Spaces follow commas in argument lists.

foo(a, 3.14159, "jmol");

• Lines should be no more than 80 characters wide.
• Break lines inside argument lists so that the parameters line up vertically.

  foo(longParameter1,
      longParameter2,
      param3, param4);

• Generally, expressions that must be broken should finish each line with an operator. Parentheses may also be desired in these cases.

  a = (b +
       c + d);

• Open brace goes on the line that starts the block. Close brace goes on a line by itself.

  if (condition) {
    ...
  } else {
    ...
  }

  while (condition) {
    ...
  }

• In cases of very simple if statements or cascading else/if statements then the following is an acceptable format that does not introduce an unnecessary amount of white space:

if ( )
  { xxx; }
else if
  { xxx; }

OR

if ( ) { xxx; yyy; }

• Loop indexes start at 0, not 1. A loop index starting at 1 deserves an explanatory comment.
• In general, for loops should look like

  for (int i = count; --i >= 0; ) {
    ...
  }

  for (int i = 0; i < count; ++i) {
    ... 
  }

• The only valid comparison operators for loop termination are < and >= ... anything else is probably a bug. If you are really sure that it is not a bug then put a comment in the code.
• Use long descriptive variable names and method names. Do not be afraid of typing.
• Line-by-line comments within the code are discouraged ... except in very special circumstances. If you put in lots of comments like this then you may find them deleted.
• If you feel obligated to insert comments put them as javadoc before the function body.
• If your code is changing then do not put in comments. Bad/outdated comments are worse than no comments.
• You may want to look at The Elements of Java Style by Vermeulen, et al.