Notes on Style by Sean Broadley (Last updated Jan 20)


Names: A rose by any other name...

Names of variables, methods, classes and interfaces should be useful. If an int variable represents kilometers call it "kilometers", don't just call it "x".

Names of variables, methods, classes, and interfaces should follow the standard Java naming scheme (never mind that Java already messed this up with instanceof and the names of all the Color constants):

AaaaAaaa...
for classes and interfaces, eg Counter and NewCounter
aaaaAaaa...
for methods and variables, eg counter and buttonClicked()
AAAA_AAAA_...
for constants, eg SCREEN_SIZE

Note that already this has been useful for us, as it let us tell which was Counter (the class) and counter (the int variable that class used).

Files:

Each file you hand in should include this comment at the start:

 
  /*  Name:            Your Name 
      Username:        Your Username 
      Lab Section:     Your Lab Section #, Meeting Time and Place
      Lab Instructor:  Your Lab Instructor's Name or Username 
      Assignment:      Number and Due Date of The Assignment 
  */  
After this goes the import statements (if any), eg:
      import java.awt.*;
Classes:

Each class should start with a comment a lot like this:

  /**
   *  Class MyClass <insert sentence explaining what this class does>
   *  Last Updated: <date>
   */
If you cannot explain what the class does in a readable declarative sentence then the class is probably doing too much: consider breaking it up. (Unless we've told you what each class should do as part of your assignment).

The first thing in each class should be declaration of the class's variables.

public class MyClass extends YourClass { 
  int chickensOnScreen; //number of chicks displayed at any one time
  // etc...
After declaring the class's static and instance variables, then put the constructors. After the constructors, go on to the other methods.

Methods:

Do not try to make a method do more than one well-defined task, and its name should mirror that task. If you cannot name a method easily that's a bad sign: either you don't know what you're doing and should stop for thought, or it is doing too much and should be broken up.

Each method should start with a comment that says what it does.

For example,

  // Displays on a ChickenFrame all the chickens in the chickenArray
  private void chickenDisplay (ChickenFrame chickFrame) { 
    // ...  
  }
If a method is longer than about half a page (including comments), it's probably too long and should probably be broken up into several methods.

Variables:

A variable's name should tell people what it does. If the name is not enough to do that, add a comment after it explaining. For example,

   int roomTemperature;  // temperature in the room, in Fahrenheit.
   int patientTemperature; // temperature in the patient, in Fahrenheit.
If you're declaring a lot of variables you may want to group them with comments. For example,
   // Temperatures (all in Fahrenheit).
   int temperatureInside;
   int temperatureOutside;

   // Display options.
   int chickensOnScreen;  // number of chicks on screen at any time
   final int SCREEN_SIZE = 100;  // display is this size
   Color backgroundColor;
Indenting:

We should say something sensible about indenting

White Space:

White space is the space you put into your code by using tabs, new lines, and, well, spaces.

The Java compiler doesn't insist that you use white space, but we do.

To see why we care, look at how hard this is to read:

public class Sports{public static void main(String[] args) {Hoosier a=new Hoosier();Hoosier b=new Hoosier();Hoosier c=new Hoosier();a. cheer();b.cheer();c.cheer();}}class Hoosier{void cheer(){int dice;dice =(int)Math.round(Math.random()*5+1);switch(dice){case 1:case 2:System. out.println("I-N-D-I-A-N-A!");break;case 3:case 4:System.out.println( "Go IU Beat Purdue!");break;case 5: case 6:System.out.println( "Hoosiers! Hoosiers!");break;}}}
Please use a lot of white space.

Make it easy to tell at a glance what is happening where.