Style Guidelines for Dr. Hasker's section of SE 2800

Rules for Repositories:

• Do not check in .class and other generated files. You may check in a .jar designated for deployment, but it should be a tested version of the system placed in a special deployment folder.
• Have a single .eap project file in a doc folder at the top level. The doc folder should also have .pdf files for each delivered document so your instructor does not need to open EA to view your documents.
• Check in project files so that your instructor can build your system. For Eclipse projects, this means checking in .project. For IntelliJ projects, this means checking in .iml files and the .idea folder.

All source files must meet the following requirements:

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

  /* 
   * Course:     SE 2800
   * Author:     your name
   * Date:       date started
   * Purpose:    goal for code in this file
   */
  

  Note the purpose should describe what problem is being solved by the file. "Contain the XYZ class" is not a purpose. Each file should generally have one author, but if you do have multiple authors then make it clear who did what.
• Ensure that all indentation is consistent (3 or 4 spaces for each indentation, indenting to show flow of control).
• Absolutely no tab characters in your file.
  • To turn off tab characters in Eclipse, click on Window|Preferences, expand Java and Code Style, and click on Formatter. Click on New... to create a new profile based on your default, click OK, Edit..., and in the Indentation item set the tab policy to Spaces only. Click on OK twice to close the preferences window.
  • To turn off tab characters in IntelliJ, click on File|Settings, open the Code Style settings, click on General, and make sure "Use tab character" is not checked.
• Use a consistent style for braces - generally braces in control statements should all be on their own lines or at the end of the previous line.
• Use blank lines to separate methods and separate attributes from methods.
• Use spaces around operators such as * and +.
• Do not put a space before parameters or arguments, but do have one space after each comma. For example:

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

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

  String constants rarely need to be named.
• Pay careful attention to names of test routines (such as JUnit tests). The name should capture the purpose of the test in clear enough language that an outside developer can understand why the results of these tests matter.
• Unless the same value is used in many places, do not use named constants in test code. Named constants in tests generally create maintenance problems.
• All data must be marked as private or protected. No public data, and no package-visible data.
• Methods and functions need to have a single purpose. For example, writing code to read data into a collection, process all the items in the collection, and then print out particular values, is probably doing too much all 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. If you can justify a longer method, then you are probably fine, but look closely for ways to break long sections of code into smaller pieces.
• 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. Most problems require at least two classes.
• Do not use exceptions for normal processing. For example, it is a bad idea to use exception handling to deal with cases where data is not in 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.

Modern IDEs can be used to fix most formatting issues:

• Eclipse: open each source file and select Source|Format.
• 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.