Style

You are expected to use good style in all your programming assignments. By "good style" I mean programs that are easy to read, understand, debug, maintain, and modify.

There are two aspects to good style. Roughly, these are the syntactic and the semantic aspects.

Syntactic style is largely machine-checkable; it means having good indentation, good spacing, proper use of braces, etc. Some of this is covered in my Simple Style Rules lecture from last semester. Eclipse will do much of this for you; In Eclipse, go to Window > Preferences > Java > Code Style > Formatter, and under Select a profile: choose Java conventions [built-in]. Do not use C++ formatting conventions!

Semantic style is a lot harder to define. It basically means things like: Don't write convoluted code, keep your methods short and single-purpose, don't repeat yourself (DRY), use extension only when you have a true is-a relationship, etc. I talk a lot about this in both CIT591 and in CIT594.

Javadoc

Basically, everything that can be Javadoc'd, should be. This includes classes, interfaces, fields, methods, etc. I make two exceptions to this rule:

• If it's marked as private, I don't require Javadoc; but I do recommend Javadoc for all methods, even private ones.
• If you use meaningful names for an enum declared within a class, I don't see the need for Javadoc.

The purpose of Javadoc comments is to tell the user how to use the method (or class, or exposed field, or whatever). If I cannot tell from your Javadoc how to use the thing, your Javadoc isn't any good. It's that simple. Oh, and please try to use good English--your Javadoc is intended to be seen by other people.

Javadoc for a method should use all appropriate @param, @result, and @throws tags. Javadoc for any sort of class should include an @author tag and maybe a @version tag.

JUnit tests

I won't go into the reasons for JUnit testing here. However, if you are using them correctly, you are (1) writing tests as you go along, preferably before writing the method to be tested, and (2) running your tests frequently--as in, every five minutes or so. Doing it this way helps you get your program running correctly; writing tests after the program is done is just extra wasted effort.

• Write JUnit tests for every non-private method that performs computations. (Methods should not both perform computations and do input/output.)
• Test "edge" (boundary) cases, as well as the "normal" cases.
• Test that methods throw all the exceptions they are supposed to throw.
• Your JUnit tests should not produce any output (at least, none that you have to look at)--just a green or a red bar.
• There is no good way to test GUI-building methods, so don't try.
• It is possible to test methods that do input from a file, and it is possible to write output methods in such a way as to be testable, but it is more hassle than other kinds of unit tests. You are not required to test input/output methods.

Blackboard

Assignments must be submitted via Blackboard. Email will not be accepted.