Naming

Classes, Interfaces, Enums

It is difficult to explain exactly what makes a good name, but there are plenty of bad ways to name your classes. You want every file that you create to have a concise name that reflects what it does. A class that is named Word should not be running a simulation of a galaxy.

You should avoid names that don't convery much information, like Data, Info, or Engine. You should also avoid tacking these unhelpful words onto otherwise good names. If you have a class that represents a star, call it Star, not StarData.

A good way to name interfaces is to name it according to what can be done with classes that implement that interface. For example, an interface that represents something that has spatial coordinates can be named SpatiallyLocatable. This makes it easier to recognize an interface compared to a class.

Methods

Method should also have informative names. do() is not a good name for a method.

With regards to accessors and mutators, there are two commonly used formats:

• value() and value(newvalue)
• JavaBeans style - getValue() and setValue(newvalue)

We prefer JavaBeans style because many tools in the Java "ecosystem" assume you will use that style.

Fields

We do not visually distinguish instance fields from local variables. Some style guides encourage a style that starts or ends fields with an underscore. We do not. Instead, we ask you to keep your classes and methods simple enough that confusion is unlikely.

Static field names should be all uppercase, for example static int BEST_NUMBER = 1338. Quite often they'll be final too. Static or not, you should mark a field final if it is not intended to be reassigned. We love immutable classes.

Encapsulation and Package Structure

Make sure to employ proper information-hiding in your classes. Fields in your classes should never be declared public in order to ensure that outside forces can't modify your fields. You should use accessors and mutators to allow outside access to your instance variables (only if they need to be modified!), which allows the programmer much more control. You can, for example, prevent setAge(-3); from working if that is nonsensical. Be sure that your getters do not hand out references to modifiable inner state of your class.

Java has four levels of visibility for fields, which are described in detail here. Most of the time it is appropriate to use the private keyword, and write accessors and/or mutators for the private field. However, in some cases it is better to use no modifier, making the field available to all classes in the same package. This is useful when you are implementing a part of your program that requires multiple classes working together. For example, if you are implementing a Graph class, you will probably also need Node and Edge classes, and the fields of Node and Edge might be package-visible so Graph can easily manage them. A more conservative strategy is to make fields private, and make the getters and setters package private.

You should be using packages wisely. You might have one package named after the project in question, and it might have only Main and a few very project specific classes. If you build a data-structure, you might have a package for the that type of structure. For example, List is in the collect package with many other kinds of collections. Resist the urge to have a util package. That's a sin of the same variety as naming your class Data

Coding Style

Exceptions

Handle exceptions! We see code like this too often:

try { 
  something();
} catch (SomethingException e){ 
  e.printStackTrace(); 
}

Don't do this . This defeats the purpose of having exceptions if you just ignore them and print an almost always useless (to the user) stack trace. A user should never be exposed to your program internals in this fashion, so printing stack traces will be treated like an uncaught exception.

Iterators

If you wish to use an iterator, please use a for-each loop rather than a for loop whenever possible. You intent is clearer, and the code is easier to digest (by humans).

Comments

Write useful comments. There are two types of comments we expect.

Method Comments — If the method is public, it should have javadoc style comments. Javadocs are like regular multi-line comments, except they are delimited by /** and */ instead of the usual /* and */. You can generate documentation from your javadoc using mvn site as described in the boggle project.

A concise guide is to Javadocs can be found here:
http://students.cs.byu.edu/~cs240ta/fall2012/tutorials/javadoctutorial.html
A more complete guide can be found here:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Inline Comments — When writing a method you should always comment on what the method will be doing and what needs to be done. Inline comments will help you figure out what has been done and what needs to be done. Also it will help people look at your code and understand what it is actually doing.

README

There are a few things we require you to write in the README.

Errors/Bugs - Write about all the errors that your program has and how to reproduce them. If a TA finds an error and knows how to reproduce it, he/she will be able to correct it and grade it more accordingly. It won't help you to cover up your errors. The TA will probably end up finding it and assume you did not test your program properly.

Design Decisions - We expect you to write about the design decisions you have made for the project. If you don't think a regular person could come up with the algorithm you wrote, explain how it works. Don't be too specific, the lower level explanation should be in inline comments. Finally, also discuss why you chose to use certain data structure or why you created one, all high level explanations as well.

Tests - Talk about all the tests that have been written for the assignment. Explain how each test ensures that a part of the program works.