CIT 594 Rules for Assignments
Spring 2008, David Matuszek

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 CIT591.

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:

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 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.

Blackboard

Assignments must be submitted via Blackboard; email will not be accepted. If more than one file is required, files should be zipped; .rar and other nonstandard formats will not be accepted.