Style Guide | SoftConst2x

UBCx Software Construction Style Guide

Below are the style conventions we will be using for this course. They are mostly drawn from the Google Java Style Guide. If you are curious about something not mentioned here, feel free to look it up there. However, if there is any discrepancy between the two, take this document as correct.

Contents
Class Organization Initialization Getters and Setters Method Specification	Braces Empty Blocks can be Concise Whitespace Naming

Class Organization:

Classes should be organized in the following way:

Constants
Fields
Constructor
Getters
Setters
Public Methods
Private Methods

The order of the fields should match the order of the constructor and the order of the getters (and setters).

Initialization:

Fields are usually initialized in the constructor, rather than in the field itself.

Example: the constants, fields and constructor for the DrawingEditor class in SimpleDrawingPlayer.

public class DrawingEditor extends JFrame {

   public static final int WIDTH = 1000;
   public static final int HEIGHT = 700;

   private MidiSynth midiSynth;

   private List<Tool> tools;
   private Tool activeTool;

   private Drawing currentDrawing;

   public DrawingEditor() {
      super("Drawing Player");
      initializeFields();
      initializeGraphics();
      initializeSound();
      initializeInteraction();
   }

Getters and Setters:

Getters and setters should be written on one line, and arranged together in a block.

Example: The getters from the Shape class in SimpleDrawingPlayer.

// getters
public int getWidth() { return width; }
public int getXCoord() { return x; }
public int getYCoord() { return y; }
public int getHeight() { return height; }
public boolean isSelected() { return selected;}

Method Specification:

All methods should have a specification of the form REQUIRES, MODIFIES, EFFECTS (or later in the course, in a javadoc).

If any of REQUIRES, MODIFIES or EFFECTS are empty, they can be omitted.

Braces:

Braces are used with if, else, for, do and while statements, even when the body is empty or contains only a single statement.

Braces follow the Kernighan and Ritchie style ("Egyptian brackets") for nonempty blocks and block-like constructs:

No line break before the opening brace.
Line break after the opening brace.
Line break before the closing brace.

Line break after the closing brace, only if that brace terminates a statement or terminates the body of a method, constructor, or named class. For example, there is no line break after the brace if it is followed by else or a comma.

Example: the draw method from the Shape class in SimpleDrawingPlayer demonstrates most of the rules above.

public void draw(Graphics g) {
    Color save = g.getColor();
    if (selected) {
        g.setColor(PLAYING_COLOR);
    } else {
        g.setColor(Color.white);
    }
    g.fillRect(x, y, width, height);
    g.setColor(save);
    g.drawRect(x, y, width, height);

    if (playLineCoord > 0 && playLineCoord < width) {
        g.setColor(Color.red);
        g.drawLine(x + playLineCoord, y, x + playLineCoord, y + height);
        g.setColor(save);
    }
}

Empty blocks can be concise:

An opening and closing brace can be on the same line with nothing between them.

Block Indentation:

Each time a new block or block-like construct is opened, the indent increases by two spaces. When the block ends, the indent returns to the previous indent level. The indent level applies to both code and comments throughout the block.

One Statement per Line:

Each statement is followed by a line break.

Whitespace:

A single blank line appears in the following cases:

Between consecutive members or initializers of a class: fields, constructors, methods, nested classes, static initializers, and instance initializers.

Exception: A blank line between two consecutive fields (having no other code between them) is optional. Such blank lines are used as needed to create logical groupings of fields.

Between statements, as needed to organize the code into logical subsections.

Example: In SimpleDrawingPlayer, the createTools method uses blank lines to break the method into distinct parts: setting up overall tool behaviour, setting up individual tools, and then setting the active tool.

private void createTools() {
   JPanel toolArea = new JPanel();
   toolArea.setLayout(new GridLayout(0,1));
   toolArea.setSize(new Dimension(0, 0));
   add(toolArea, BorderLayout.SOUTH);

   ShapeTool rectTool = new ShapeTool(this, toolArea);
   tools.add(rectTool);

   MoveTool moveTool = new MoveTool(this, toolArea);
   tools.add(moveTool);

   ResizeTool resizeTool = new ResizeTool(this, toolArea);
   tools.add(resizeTool);

   DeleteTool deleteTool = new DeleteTool(this, toolArea);
   tools.add(deleteTool);

   PlayShapeTool playShapeTool = new PlayShapeTool(this, toolArea);
   tools.add(playShapeTool);

   PlayDrawingTool playDrawingTool = new PlayDrawingTool(this, toolArea);
   tools.add(playDrawingTool);

   setActiveTool(rectTool);
}

Naming:

Package names are all lowercase, with consecutive words simply concatenated together (no underscores).
Example: simpledrawingplayer.model (not simpledrawingplayer.drawing.model or simpledrawingplayer.drawing_model).
Class Names and Interface names are written in upper camel case (UpperCamelCase) and are typically nouns or titles of roles.
Examples: DrawingPlay, MidiSynth, ShapeTool.
Test classes are named starting with the name of the class they are testing and end with Test.
Examples: DrawingTest, ShapeTest.
Method names are written in lower camel case (lowerCamelCase) and are typically verbs or phrases.
Examples: selectAndPlayShapes, addToDrawing, stopPlayingWhenDone.
Constant names are written in constant case (CONSTANT_CASE), which is all capital letters with words separated by underscores.
Examples: PLAYING_COLOR, MUSIC_LINES_SPACE.
Non-constant Field Names, Parameter Names, and Local Variable Names are all written in lower camel case (lowerCamelCase).

UBCx: SoftConst2x Software Construction: Object-Oriented Design