Hasker's SE 2811 Style Guide

In addition to correctness, solutions will be graded for style and design. Detail is given below; but the quick list is

• meaningful identifiers following standard capitalization rules
• format code nicely with spaces around operators and no hard tabs
• document each file as listed below
• minimal scope for variables
• methods, classes have clear purpose
• good exception processing
• Javadoc when appropriate
• use standard libraries and compile without warnings
• be very careful about what you check in to repositories

• Document the responsibilities for each class.

• Use meaningful names for identifiers. One-letter names for loop variables is ok, but not method names or attributes.

• Ensure you follow standard capitalization rules with capitalized CamelCase class names, ALL_CAPS constants, and lowerCamelCase methods and variables.

• Format your programs consistently and nicely, including
  • ensuring that all indentation is consistent (3 or 4 spaces for each indentation, indenting to show flow of control)
  • ensuring there are no tabs in your file (if you don't know how to fix this, ask!)
  • ensuring that lines are no longer than about 100 characters
  • using blank lines to separate methods and separate attributes from methods
  • adding spaces around operators such as *, +, <, ==, &&: x * y < a, not x*y<a
  • one space after each comma; for example:

            public void printResults(String[] items, int first, int last,
                                     String key);
    

  • keeping lines shorter than 100 characters

• Include a comment at the top of each source file you submit giving basic information:

  /* 
   * Course:     SE 2811
   * Term:       Winter 2018-19
   * Assignment: assignment name
   * Author:     your name
   * Date:       date started
   */
  

  This will allow identifying misplaced files and acts as a signature saying you wrote the code.

• If numeric constants are used in multiple places (such as the maximum length of a string), you must declare a final value for that number and use it appropriately. For example:

          static final int BUFFER_SIZE = 50;
          double[] toProcess = new double[BUFFER_SIZE];
  

  Except in rare circumstances, do not declare named constants for test code. Named constants in tests just creates maintenance problems.

• All variables must have minimal scope. That is, they should not have any more visibility than necessary for the design. Variables which are local to a method should be declared within it, and attributes should private or protected, Package scope can be used, but only when absolutely necessary.

• Methods (aka functions) need to have a single purpose. For example, computing some result and printing it out in the same method is doing too much at once. Break such code into multiple methods/functions. Generally, no method/function should be longer than about 15 lines of code unless it has a switch statement in it, and even then the individual cases should be just a few lines long. Repeated code should be factored into additional, possibly private, methods.

• Likewise, classes should have a clear purpose. If a class is responsible for lots of different things, then some of those responsibilities should be given to a different class.

• Use exceptions appropriately:
  • Do not use exceptions for normal processing. For example, do not use an exception to terminate a loop when reaching the end of a container.
  • Do not catch Exception - always find a much more specific exception to deal with the error you are attempting to handle.
  • If you catch an exception, deal with it in some reasonable fashion such as printing an error message and going on to the next data item. Never simply catch an exception and ignore it without a strong, documented reason.

• When required, provide Javadoc documentation for all classes and public methods other than getters and setters. You do not have to provide Javadoc documentation for constructors or data unless there is something notable about the element that may need to be captured for future maintenance.

• Feel free to document your code in ways beyond required Javadoc, but make sure your documentation adds information. Comments like

          distance += 10; // add ten to distance
  

  are worse than useless. Don't write a comment if its opposite is obviously false.

• Your solution must build cleanly with no warning messages and using only standard Java libraries.

• Do not add .class files or libraries to your project repositories (like Bitbucket or Gitlab).

You can fix most formatting issues by doing the following in IntelliJ:

• Select File|Settings...
• Click on the + sign beside Code Style and then click on General
• In the right window, clear the box "Use tab character" (that is, make sure it's not checked)
• Click on OK.
• Select Code|Reformat Code...
• Make sure your file is selected (or all files in the directory) and click on the Run button.

Note: