CSE341 -- Assignments -- Java style guide

Some students have requested more guidance about what we consider acceptable style for the homeworks. Therefore, please observe the following guidelines for the Java project. As always, style rules are guidelines only; there are always exceptions. Use your judgment. -- Keunwoo

• Indentation and braces
• Naming
• Comments and documentation
• Code structure

Indentation and braces

We will accept any of the standard indent styles: K&R, Allman, Whitesmiths, or GNU/FSF (see here for explanations of the four styles). Please be consistent, at least within a single source file. Also, use at least two spaces for each indent level, and no more than eight.

As an exception, one-liner methods (you will probably have several of these) can be written on one line:

public class Foo 
{
    // ...
    public int getX() { return x; }
}

Naming

Use meaningful names. It is not necessary in Java to abbreviate class names; for example, the Java designers named their input stream class InputStream, not istream. Java programmers are used to long, informative type names, so don't attempt to "save space" by using cryptic identifiers.

The Java convention for capitalization is

• mixed case,
• no underscores,
• each word starting with a capital letter,
• class names begin with initial caps,
• method and variable names begin with initial lowercase,
• except that constants (final variables) are in all caps with underscores between words

public class ClassName
{
     public static final int CONSTANT_NAME = 0;
     public void methodName(ParamType paramName) {
         VariableType varName = (VariableType)paramName;
     } 
}

However, if you have already started your project using some other naming convention (e.g., C or Ada conventions) then feel free to continue using yours, as long as it's consistent.

It is common in the C++ world to name private instance variables with an initial underscore. This is discouraged in Java.

Comments and documentation

Documentation should take several forms:

• Include with your package a README file describing the overall architecture (the major classes and their interactions) in a couple of paragraphs.



• If you use any code or algorithms from other sources, document where you obtained that code in a prominent place in the source file. It would be appropriate to include a "Thanks" section in your README to acknowledge those authors as well.



• All source files should have a banner comment at the top describing the file/class name, and the class's general function.



• All nontrivial, non-self-explanatory public methods should have doc comments (use your judgment as to what is "trivial" or "self-explanatory"). Any non-obvious parameters to functions (i.e., any parameters whose names are not totally self-documenting) should have @param declarations in the doc comment. For more information about doc comments, see "How to Write Doc Comments for Javadoc" (this is a rather long document; you can skim most of it and skip down to the "Tag Conventions/Tag Comments" part).



• Groups of methods/fields that are logically related should be marked as such with regular // comments, and sometimes banners (use your judgment).



• Any tricky bits of code must come with a few explanatory comments.

See my BufferedCanvas.java file for an example of how to document your classes. We will not expect quite as much documentation for every one of your class files, but it should give you an idea of how to do it.

Code structure

You should use good object-oriented design as described in lectures. Here are some points to remember:

• Do not make anything public when you can make it private or protected. Do not make anything protected when you can make it private. This preserves information hiding.



• Do not use public instance fields (data members) unless your class is really a behaviorless struct. Otherwise, you should make your fields private and provide public accessor methods. For example, rather than the following:

  public class GameActor {
      public int x, y;
      // ...
  }
  

  you should use the following:

  public class GameActor {
      private int x, y;
      public int getX() { return x; }
      public int getY() { return y; }
      public void setX(int x) { this.x = x; }
      public void setY(int y) { this.y = y; }
      // ...
  }
  

  The latter frees you to make implementation changes in the future. It also frees you to make interface changes in the future; if, for example, you decided to make GameActor an Immutable class, you could remove the set methods and the compiler would tell you all the places you need to change your code.



• Your classes should each represent a distinct concept. You should not find yourself cramming tons of unrelated code into a single class (this is sometimes derogatorily referred to as "Procedural Object-Oriented Programming" or "POOP"). Exception: it is sometimes legitimate design to collect several static utility methods in a single utility class (e.g., java.lang.Math).