Skip to main content

Style Guidelines

You only write code once, but read it many times. Having clean, organized, legible, intuitive, and understandable code is important for those who read it: whether it be for debugging purposes (yourself, a peer, or a TA), for style grades (a TA), or even for judging your coding abilities and organization (a potential employer/co-worker). Yes, your code may run and solve a given problem whether it is organized or not. But, writing your code in a clean and organized way from the start will benefit you in the long run.

General Guidelines

Code must compile: Any code you submit must compile. If it does not compile, we won’t grade the assignment and you will lose all the points for the assignment.

Don’t repeat yourself (DRY): If you find yourself writing the same or similar code two or more times, consider whether it could be put in a separate method.

Break up large methods: If a method has many parts doing distinct and non-overlapping functions, consider breaking up the method.

Don’t rewrite existing code: The Java standard libraries provide implementations of a great number of methods and data structures: use them! The java.util package will prove especially useful in this course.

Comments: Comment your code where necessary e.g. complicated functions, specifying method behaviors, stating invariants. When documenting methods, write Javadoc. Within methods, good style and good variable names are usually enough: don’t over-comment.

Java

You should adhere to the Google Java Style Guide with the following exceptions:

The easiest way to format your code correctly is to understand the style guideline and get used to seeing code that looks good. However, most modern IDEs and text editors have code formatters, which we encourage you to configure and use (see below for instructions).

Upon submission, our grader will lint your code and point out anything wrong with your style, which you should fix.

OO (Object-Oriented) Concerns

Avoid public fields: Use getters and setters instead. If a class Point has an instance variable x and you are working with a Point point, you should not find yourself writing point.x. Instead, declare x as a (package-)private variable, and write a getter method, point.getX(). One exception in which this rule may be waived is if the variable x is marked as final.

Use appropriate modifiers for all types: In general, restrict visibility as much as possible. If need a refresher on modifiers (like protected, final, static), refer to the Oracle pages on access-level modifiers and instance/class members.

Eclipse Code Formatter Setup Instructions

The Google Java Style Guide is widely used, and developers have created files to help automate the Eclipse Code Formatter setup. The CIS 121 staff has modified the original setup file to include the exceptions to the guidelines we expect you to follow (as listed above). We highly encourage you to setup this auto-formatter.

  1. Right click this link and download the file, which contains the CIS 121 style specifications.
  2. Under Window -> Preferences (Windows) or Eclipse -> Preferences (Mac), select Java -> Code Style -> Formatter
  3. Click Import, and find the eclipse-cis121-style-guide.xml file you downloaded in Step 1.
  4. Click Apply and OK. You are all set!

Please go to Office Hours for help if you run into any issues.

How to Use the Auto-Formatter

Mac Users: Command + Shift + F
Windows Users: Control + Shift + F

Alternatively, you can do it the old-fashioned way through the main menu: Source -> Format.

Warning: The auto-formatter does not catch and fix every style error, but it does fix the vast majority of them. You should be using the auto-formatter as a second line of defense.

Note: You can also setup the formatter so that upon saving a file, it auto-formats for you. Some people really dislike this feature as it can get annoying, but you can try it if you’d like. Instructions can be found here.