Always obey the rules, prefixed below by R. There will be a significant grade penalty for breaking them. Like grammatical mistakes in English, if you break the rules it is quite distracting, and may cause serious confusion for your reader.

Guidelines, prefixed below by G, should be generally followed or your program becomes hard to read, but violations are not as serious as breaking rules, and exceptions are sometimes appropriate.

1. R: Start every assignment file with a special comment line containing your lab start time, the assignment number, and the names and usernames of all your assignment team members. For example: // 9:30 lab, a2 by Wilma Wiz, wwiz, and Harry Hacker, hhacker
   
2. G: Use descriptive names for all identifiers (variable, method, and class names). Generally avoid single letter names such as a and x . There are a couple times when short names are appropriate:
   • the identifier is being used as a index counter (in which case i and j are fine)
   • all uses are within a few lines of its declaration, and its type makes clear its significance.
     
3. R: Use the standard Java naming conventions.
   • Class names begin with a capital letter, use capital letters to begin new words, and do not contain underscores. For example FrameWindowController, not frame_window_controller.
   • Variable and method names begin with a lower case letter, use capital letters elsewhere to begin words, and do not contain underscores. For example mousePosition, not Mouse_position.
   • Constants use only capital letters and separate words with underscores. (Constants are always declared static, and are also declared final unless their value cannot be provided by an initializer.)
   • Avoid using dollar signs. The compiler uses them for its own purposes (related to nested classes) with which you do not want accidental conflicts.
     
4. Make good use of white space.
   • R: Start a new line after each semicolon and right brace. Note: Closing braces in Java are handled very differently from closing parenthesis in Scheme (in which multiple closing parenthesis on the same line are common).
   • R: Do not use tab characters, since printing and editing environments differ in how they interpret tabs. In DrJava, the tab key uses spaces to indent the current line, or all highlighted lines, rather than inserting a tab character.
   • R: Do not put more characters on a line than fit on one line in all the printing and editing environments that you code will be exposed to. For this course, that is at most 85. When in doubt, limit yourself to 80 characters per line. Continue lines with an extra level of indentation, beginning the new line with an operator if possible (which makes it easy to see that it is a continuation).
   • G: Use blank lines to delineate different areas of your code:
     • after a group of import declarations
     • around class headers (consider a comment just before a class as part of the header)
     • after each group of instance and class variable declarations
     • between method declarations
     • separating logically related groups of code
   • G: Use a space after each comma, before each left brace, and around most binary operators.
     
5. R: Use a standard indentation convention consistently. If you start lines in standard places, DrJava will do this for you, and will fix broken indentation if you press tab. There are several common indentation conventions, but all obey the following rules.
   • Use 2, 3, or 4 spaces per indentation level, and use the same amount throughout a program.
   • Use a line's indentation to reflect its nesting level in the syntactic structure of the program. More indentation means deeper nesting. (Braces may, depending on the indentation style, be considered to be at the same level as their contents or at the level above.) For example, this means:
     • all methods and field declarations begin with the same indentation.
     • all code within method bodies begin with the same indentation, unless it continues part an unfinished statement or declaration.
6. G: Use magic numbers only in constant declarations. A magic number is any number other than -1, 0, 1, and 2. This forces you to give meaningful names to mysterious quantities, which goes a long way toward making programs self-documenting.
7. G: Use meaningful comments to clarify your program.
   • Provide comments for program characteristics that are not readily apparent from the names you have chosen and knowledge of common Java language mechanisms. Don't clutter up your program with comments that only says what is obvious from the code. Use of good class, variable, and method names greatly reduces the need for comments.
   • Javadoc /** ... */ comments are preferred just before public methods and classes.
   • Use /* ... */ comments for comments of more than two lines.
   • Use // comments for comments at the end of lines or that only apply to the immediately following line, or small group of lines ending in a blank line.
   • Use /// comments to indicate stubs and development notes (to be removed before the program is completed).
     
8. G: Use public and private visibility modifiers.
   • Avoid protected and package (no modifier) visibility.
   • Declare fields to be private, except constants that need to be referenced from outside the class. Exception: "record" classes that exist only to contain multiple values and do not have getters must have public instance variables.
   • Declare methods to be private if they are not used outside the class and are not used to implement an interface.
   • Declare classes used to start a program to be public.
9. R: Group class members in a consistent and meaningful way. This usually means grouping by kind and in order of decreasing visibility. For example, put constants first, then instance variables, and finally methods. Within each of these groups, put public members before private members. Some programmers prefer to give priority to visibility, listing all public members, regardless of their kind, before private members. The following style is recommended: Group class members in the order class variables, instance variable, constructors, methods, and finally nested classes, with the exception that private fields used only by a single method are usually placed just before the method. Within each group, order by decreasing visibility, except for methods, which are grouped with related methods together, starting with the most important and visible.
10. R: Put field modifiers in the standard order: visibility (such as public or private) first, then static (if present), and finally final (if present).
11. G: Clarity is almost always the overriding style concern.
    1. Avoid unnecessarily complicated code. Rework the code if you see a better way (called refactoring, another precept of extreme programming).
    2. Clarity is more important than efficiency, unless the efficiency improvement is important to the application. (For most "improvements" programmers are tempted to make in the name of efficiency, it is impossible to detect an efficiency improvement, and sometimes they actually slow the program down by making the compiler's job more difficult.
       
12. G: More guidelines for naming:
    • Pluralize names of collection references; for example Sprite[] sprites = new Sprite [NUM_SPRITES];
    • Generally avoid abbreviations in names, including vowel dropping: e.g. use customerName instead of custName and message instead of msg. Exception: use num instead of numberOf, as in numFields instead of numberOfFields.
    • If a variable has a small scope and no particular meaning beyond that conveyed by its type, it often works to abbreviate its name to a single lowercase letter for each element of its type name. For example, sb may be a good name for a StringBuffer..
    • Choose names from parts of speech such that programs make some sense as English
      • Class names: nouns or noun phrases
      • Interface names: nouns or adjectives
      • Method names: verbs or verb phrases
      • Boolean variable names: predicative verbs (which make sense following "if"), e.g. done, isFull
      • Other variables: nouns
      • Exceptions: end with the word Exception
    • Avoid the use of negative boolean variable names; for example use done instead of notDone.
    • If a parameter exists so its value can be assigned to a field, name the parameter after the field: e.g. public void setCount(int count) { this.count = count; }
      

13. Avoid dead code that can never be reached due to local program structure. This most commonly results from including an else clause after a series of else ifs that exhaust all possibilities. Instead, delete the last if (which would surely be true) and replace it with a comment indicating the condition.

    Wrong:

    if (x <= y) {
      doThis();
    } 
    else if (x > y) {
      doThat();
    } 
    else impossible();
    

    Ok:

    if (x <= y) {
      doThis();
    } 
    else { // x > y
      doThat(); 
    }
    

    It is still a good idea to detect and report errors that might result from errors in other parts of a program or invalid input resulting in data structures or other forms of program state that are inconsistent with the program design.Thus if local logic analysis does not prove that data is in the expected form in an else clause (or switch default clause), the clause should be replaced by an if statement that tests for the expected form and has an else clause that raises an exception.
    
14. Avoid using else { if when else if is appropriate. If an else clause includes an if followed by one or more other statements, it is necessary to follow the else with a left brace; otherwise, do not do so. Also do not increase the level of indentation for an if expression immediately following else when extra braces are not used . Though the if expression technically introduces an extra level of syntactic structure, for indentation purposes it is treated as part of the same structure as the else it follows.

    Wrong:

    if (x == 1) one();
    else {
      if (x == 2) two();
      else moreThanTwo();
    }
    

    Also wrong:

    if (x == 1) one();
    else if (x == 2) two();
         else moreThanTwo();
    

    Ok:

    if (x == 1) one();
    else if (x == 2) two();
    else moreThanTwo();
    

15. G: Avoid using Vector if its efficiency is of concern: it is amazingly inefficient. java.util.ArrayList is similar, but unsynchronized, so it is faster. Insterion and deletion are still linear time operations, though. 
    
16. R: Use exceptions only for rare events: they are quite inefficient.
    
17. R: Use assignment operators, such as =, ++, --, and +=, only as statements (so they are used only for the assignment, not for the value they return). Exception: = may be used to advantage in a while loop condition when the alternative is duplicating code or breaking out of the middle of the loop.
    
18. G: Break up long declarations. If a method or class declaration is getting long (more than about 30 lines for a method and a page or two for a class), it is often a good idea to break it up.
    
19. G: Use class extension only when an instance of the new class "is a" instance of the extended class. Never use extension simply to avoid using dots in names! In other instances in which you may be tempted to use extension, delegation or composition are generally appropriate.
    
20. G: When declaring a collection, include a comment "of type " giving the type of the objects in the collection.