594 Rules for Assignments
Spring 2007, David Matuszek
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.
Basically, everything that can be Javadoc'd, should be. This includes classes, interfaces, fields, methods, etc. I make two exceptions to this rule:
private, I don't require Javadoc; but I do recommend Javadoc for all methods, even private ones.
enumdeclared 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
@throws tags. Javadoc for any sort of class should include
@author tag and maybe a
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.
privatemethod that performs computations. (Methods should not both perform computations and do input/output.)
Assignments must be submitted via Blackboard. Email will not be accepted.