Coding standards for Colossus

• * Do not put tab characters in code, period. Use spaces only. There is no standard tab stop in Java, so tabs will look bad for anyone whose editor is set up differently than that of the person who put tabs in the code. Configure your editor to emit the appropriate number of spaces rather than a hard tab when you hit the tab key. (Of course, Makefiles are an exception, because you have to use tabs in them. Ick.) "ant fix" converts tabs to spaces for you, but it assumes a tab stop of 8 unless you change it.
• * Wrap code at 79 characters. This is a pain sometimes, but it allows easly working with the code using 80-column editor and terminal windows. (Remember, code is not just viewed through your favorite editor in your favorite GUI desktop. It's also emailed around, diffed, viewed in debugger windows, fiddled with on remove servers through network connections, etc.)
• * Put opening braces at the beginning of a new line rather than the end of the previous line. This decision has been argued for decades and will never be settled (at least not until all language designers follow Python's lead and just ditch the braces), but consistency within a project is more important than personal preference.
• Keep all member variables private, except for constants. Use get/set methods to share. (But don't automatically add an accessor and mutator for every variable, just for the ones that actually need them.) This adds some overhead up front but makes it easier to refactor code later.
• Try to comment stuff, at least at the method level for non-trivial and non-private methods. But there's no need to go overboard commenting obvious stuff. Use javadoc comments instead of regular comments where applicable.
• Every method in the .client and .server packages should be either private (if possible) or package private (if needed by other classes in the package), unless it needs to be public. And just because a method is public doesn't mean it should be called from outside the package.
• Some methods are private because they're not used outside of their class, not necessarily because they shouldn't be used outside of their class. Some classes are final because they're not currently subclassed, not because they should never be subclassed. These are optimizations for both programmers (who don't need to check to see if other classes call / override something before changing it if it's tagged private / final) and for the JVM, not necessarily final design statements. So feel free to change such things as necessary, until the interfaces are finalized and polished and other people depend upon them.
• Always do a cvs diff before you check code in. That way changes you didn't want to commit won't sneak in. And you'll be able to write a better check-in comment.
• * Fully brace conditionals, even if the clause is only one line and doesn't technically need braces. This makes the code taller, but easier to read and change.
• Keep files in Unix endline format (LF, not Windows format (CR/LF) or old Mac format (CR). This is critical for Makefiles, which will sometimes stop working if the line breaks are wrong. Java files will work either way, but it's annoying to have a mix of line breaks, false diffs caused by files getting converted back and forth, etc. so consistent Unix format is best. "ant fix" is your friend.
• Otherwise just try to follow the existing format. A foolish consistency may be the hobgoblin of little minds, but it sure makes code easier to read.

Thanks for reading this.

(Rules marked with '*' are automatically enforced on CVS check-in using Jacobe.)