Hasker's SE 2811 Coding Standard

In addition to correctness, solutions will be graded for style and design. Additional detail is given below, but here are the key points:

• Use meaningful names for identifiers except those with very limited scope (such as the parameter for a one-line function).
• Format your programs consistently and nicely, including judicious use of spaces and blank lines. Keep line lengths to about 100 characters.
• Ensure your files contain no hard tabs.
• Include your name (prominently) in all source code files you edit. Note this does not include .fxml and similar files.
• Document the responsiblities of the classes you write. For example,

          // Track owner, tenant, and number of apartment
          class Apartment { ... }
  
          // Record both available and unavailable apartments in a building
          class Building { Apartment[] available_apartments, open_apartments ... }
  
          // Track current floor and call destinations of the elevator
          // as well as its maintenance history
          class Elevator { ... }
  

  In general, the goal is to provide enough documentation that another person can understand the modules in your solution, without providing documentation that is blatently obvious from examining the code.
• Follow standard design principles including small subroutines, minimal repeated code, and tightly scoped identifiers.
• Use appropriate exception processing.
• Fix your code so it builds without compilation warnings using Java 8. Use only standard, documented libraries distributed with OpenJDK and JavaFX.
• Use lower case for repository, file, and other names unless a tool (such as javac!) mandates a different convention.
• Do not check build products into repositories, including third-party libraries.
• Do not include large amounts of dead code - code that has been commented out or otherwise disabled.

Additional detail:

• 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);
    

• Include a comment at the top of each source code file you submit (assuming you modified or wrote it) giving basic information:

  /* 
   * Course:     SE 2811
   * Term:       Winter 2021-22
   * 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. You do not need to include this information in data files such as .fxml files.
• 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 (try/catch) 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 or for special case processing on empty lists.
  • 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 GitHub).

• Do not include large amounts of dead code. For example, you might leave commented out debug messages, but not if they make the rest of the code harder to read. Any 4 or 5-line unused section of code should generally be removed.

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:

By default, Windows is configured to not show extensions such as ".java" for file names. This causes problems for engineering students. A simple fix is to enable showing extensions as discussed here.