CSC 148HH: Programming style in your assignments

Style is always a matter of taste, but taste is to a considerable extent determined by shared conventions among professionals. We suppose that this is true for writers in prose and poetry, but we are not experts in those fields. In programming, however, we are professionals, and we want to help you become professionals too.

So we're basing part of your assignment marks on your programming style. We assess your style in two ways: by an automatic style checker, CheckStyle, and by the TA marking your assignment. The TA and CheckStyle will use similar criteria, but since CheckStyle works automatically and can be described precisely -- and because the TA will only commment on your style if there seems to be a need to go beyond what CheckStyle says -- we will concentrate here on our style rules in the context of CheckStyle.

Style rules

You may well lose marks for violating any of these rules, but we'll discuss that later. Here we just state the rules.

Put only one public class in each .java file.
Write a good Javadoc comment for each class, each instance variable, each static variable, and each method. In your method comments, include @param and @return tags when appropriate.

Your method comments must mention the purpose of each parameter, and must be grammatically correct.
Each line must be less than 80 characters long including tabs and spaces. Beware of "soft returns" -- some word processors, like WordPad, wrap lines automatically. If you use such a program, make sure that you press the return key yourself.

DrJava tells you what column you're in. Look in the lower-right corner.
Use a tab width of 2 (DrJava's default), if you use tabs at all. The best way to make sure your program will be formatted correctly is never to mix spaces and tabs -- use only tabs, or only spaces. If you use a tab width of less than 2, it is your responsibility to make sure that your lines are shorter than 80 characters when we look at your program, because we will use a tab width of at least 2. DrJava is set up at school to use a tab width of 2, and you can do that at home, too, in almost all IDEs.

However, if you do use tabs for indentation, you run the risk that CheckStyle may think your lines are too long. Please also see the comments below on what CheckStyle does with tabs.
Never compare a boolean expression to true or false. For example, if you find yourself writing code like this:
```
  if (a.equals(b) == false) {
    ...
  }
            
```
replace it with code like this:
```
  if (!a.equals(b)) {
    ...
  }
            
```

If you find yourself writing code like this:

  if (a < b) {
    return false;
  } else {
    return true;
  }

Replace it with code like this:

  return !(a < b);

Similarly for assignments:

  if (a < b) {
    ack = false;
  } else {
    ack = true;
  }

Replace it with code like this:

  ack = !(a < b);

Here's a rule where we want to be careful, partly because we disagree with each other on it.

Be very careful when using return from the middle of loops, and nearly as careful with break and continue. Similarly, be careful with return before the end of a method.

Why? Because if you use these your code is harder to read and understand: unless you have a good reason, there should only be one way to exit a loop or method. Therefore, when we say "Be careful", we mean, "Be sure that you need to do it this way, and format and comment your code so that the reader can easily tell what's happening." (And in case you're wondering, we all agree on the entire contents of this paragraph -- though we might disagree on the definition of "good reason".)
Put a blank line before every comment that appears on a line by itself.
Put a blank space before and after every operator. For example, the first line below is good but the second line is not:
```
          boolean b = 3 > x && 4 - 5 < 32;
          boolean b = 3>x && 4-5<32;
            
```
Note, however, that we do not recommend or require spaces before or after the '<' and '>' in class names with type parameters (using Java 1.5's "generics"). For example, this is fine:
```
           List<String> sList = new ArrayList<String>();
            
```

When breaking up a long line, break it before an operator, not after. The first example below is good but the second is not:

          boolean b = "Hello".charAt(3) + 3 > x
            && Integer.parseInt(s) < 32;

          boolean b = "Hello".charAt(3) + 3 > x &&
            Integer.parseInt(s) < 32;

Always use braces on if, else, and loop blocks. The first example below is good but the second is not:

    if (x > 5) {
      while (i > 3) {
        // Do something
    }
    } else {
      // Do something else
    }

    if (x > 5)
      while (i > 3)
        // Do something
    else
      // Do something else

Running CheckStyle

As we mentioned, we use CheckStyle to enforce many of those rules. You can get it yourself, here:

http://checkstyle.sourceforge.net/

CheckStyle uses a configuration file to tell it what it should complain about. There is a standard configuration file packaged with the CheckStyle download, but we use our own version:

148-stylechecks.xml

(Depending on your browser, you might need to right-click on that link to save the file.)

Our configuration is somewhat less picky than the standard one, but it will still catch a lot of things you wouldn't have thought of. We don't penalize you for everything CheckStyle says, but to be sure that you will not lose style marks on CheckStyle's report, make sure that it doesn't complain at all. There may still be larger issues that CheckStyle misses and the TA does not, but that's somewhat unlikely.

A couple of things to watch out for, or not to watch out for:

As of March 2006, CheckStyle still doesn't understand that the angle brackets around type parameters (as in "List<E>") don't need spaces before and after. We won't penalize you for these "errors".
CheckStyle assumes a tab width of 8. Regardless of how narrow your code looks, if you're using tabs for indenting and you imagine your tab width is, say, 2, then CheckStyle may well report overlength lines. The cure: don't use tabs for indenting.

Figuring out your style mark

CheckStyle produces a report that can be quite long and contains a lot of details that can be hard to understand. How do we get a style mark from that report?

We decide which errors we care about most, and concentrate on those. We look through the report to count the number of violations of the style rules. Generally, a single violation of a rule isn't enough to cost you marks, but several will. We tend to set two cutoffs: if you have more violations than the high cutoff, you are assessed a full penalty point, while if you have fewer than that but more than the low cutoff, you are assessed a half penalty point. The weight of penalty points may vary, but is typically a couple of percent of the assignment value.

These are the errors that we tend to care about most (where, by "tend to", we mean that we aren't promising not to add other errors to the list):

Non-private instance and static variables
Capitalization errors for variables, methods, and classes (Variables and methods should not start with a capital, and classes should.)
Missing Javadoc comments for classes, variables, and methods
Missing Javadoc @param tags
Missing Javadoc @return tags
Misuse of booleans, for example using an if/else to return true/false
Lines longer than 80 characters
Missing braces on if, else, and loop blocks

CSC 148H: Programming style in your assignments

Style rules

Running CheckStyle

Figuring out your style mark