Go back to Course Home Page

CSCI 1933 Lab and Project Guidelines

1. Introduction and Motivation

For the first project submission, style will be a minor portion of the grade you receive and poor efficiency will only penalized in extreme cases - some comments will be expected, but efficiency will not be evaluated. This is designed to allow you to devote all of your resources to achieving proper output. However, there exist many other factors in quality production level code since efficiency and maintainability become exponentially more important as projects increase in scale. This course will introduce you to using a cohesive style and maintaining good practices that will be expanded upon in future coursework.

All content in this document will be considered mandatory for all work beginning with the second project and failing to follow the guidelines specified will result in loss of points. As the semester progresses, a larger portion of your grade on projects will be determined by the quality of the code you submit as opposed to simply producing the desired output. If you have any questions regarding what is expected on your submissions please refer all questions to the Discord forums.

2. Style Guide

Style guidelines serve to address aesthetic issues of formatting, required conventions, and clearly enforceable guidelines. The style portion of this document will be a revised and condensed version of the Google Java Style Guide.

2.1 Source File Structure

Please use the following source file (every .java file created) structure:

  1. A coment including your name and x500
  2. A comment including your partner’s name and x500 (if applicable)
  3. Import statements
  4. Exactly one class

The ordering of your class contents is a design choice you have to make, but all related code should be grouped together. This means that all class variables should be initialized in the same place and constructors should be next to each other if multiple exist. You can decide if you want your private methods next to the public methods they are associated with or if you want all public methods grouped together.

2.2 Commenting

Commenting has been a minor part of your evaluation, but will start to play a larger role. Com- menting refers to both JavaDocs and in-line comments. JavaDocs are one form of commenting that are placed on top of non-trivial functions. In-line comments should clarify individual lines or block of codes that are not obvious upon first glance, any code that is “self-documenting” (like getter methods) does not need further in-line comments. A simplified outline of JavaDocs is provided below:

  1. Description of the method
  2. All parameters and a description of them preceded by the @param tag
  3. The potential return values preced by the @return tag

An example of a JavaDoc is below for a sample problem:

/*
  Method returns a copy of a row of data given the corresponding name of the row. Assumes the input rowName will be present in this.rowLabels and is unique.
  @param public rowName a string representing the name of the row to be returned
  @returns a copy of the row corresponding to the title
*/

int[] getRow(String rowName){
  int rowNumber = -1;
  int i = 0;
  while (rowNumber == -1 && i < this.rowLabels.length){
    if(rowName.equals(this.rowLabels[i])) {
      rowNumber = i;
    }
    i++;
  }

  int[] returnedArray = newint[this.dataArray[rowNumber].length];
  System.arraycopy(this.dataArray[rowNumber], 0, returnedArray, 0, this.dataArray[rowNumber].length);
  return returnedArray;
}

2.3 Naming Rules

  • Class Names: UpperCamelCase
  • Method Names: lowerCamelCase
  • Non-constant Variables: lowerCamelCase
  • Constant and Final Variables: UPPER_CAE_DELIMITED_BY_UNDERSCORE

2.4 Indentation

Indentation should be increased each time a new block is opened and returns when that block closes. A new block happens at all conditional statements, loops, switch statements, method declarations, and classes. We do not care if you use 2 or 4 space indentation.

2.5 Braces

  • Braces should be used with if, else, for, do and while statements, even when the body is empty or contains only a single statement.
  • We are not concerned about what style you follow with regards to line breaks around braces as long as it is consistent

3. Programming Principles

3.1 Code Reusability

Non-trivial code should be reused in all cases. If the same logic is implemented multiple times, it should be sectioned off into a function and called instead of copying and pasting the code. To explain this, we will examine a solution to an adapted problem from the first midterm. Commenting have been omitted in this example. Suppose we have the following code already implemented:

public class Table {
  private int[][] dataArray;
  private String[] rowLabels;
  private String[] colLabels;

  public Table(int[][] inputArray, String[] rowLabels, String[] colLabels){
    this.dataArray = inputArray;
    this.rowLabels = rowLabels;
    this.colLabels = colLabels;
  }

  public int[] getColumn(String[] colName){
    int colNumber = -1;
    int i = 0;
    while (colNumber == -1 && i < this.colLabels.length){
      if(colName.equals(this.colLabels[i]){
        colNumbber = i;
      }
      i++;
    }
    int[] returnedArray = new int[this.dataArray.length];
    for(int j = 0; j < this.dataArray.length; j++){
      returnedArray[j] = this.dataArray[j][colNumber;
    }
    return returnedArray;
  }

Suppose we wanted to implement the getColSum function. We will examine a good and a poor oslution in terms of code reuse.

Poor example:

public int getColSum(String colName) {
  int colNumber = -1;
  int i = 0;

  while (colNumber == -1 && i < this.colLabels.length) {
    if(colName.equals(this.colLabels[i])) {
      colNumber = i;
    }
    i++;
  }
  int[] associatedColumn = new int[this.dataArray.length];
  for(int j = 0; j < this.dataArray.length; j++) {
    associatedColumn[j] = this.dataArray[j][colNumber];
  }

  int sum = 0;
  for (int i =0; i < associatedColumn.length; i++) {
    sum += associatedColumn[i]
  }
  return sum;
}

Notice the differences in the example with good code reuse. Instead of re-implementing the code from getColumn, the function is simply called and used. Not only is it 15 lines shorter, it is more readable and easier to debug.

public int getColSum(String colName) {
  int[] associatedColumn = this.getColumn(colName);
  int sum = 0;
  for(int i = 0; i < associatedColumn.length; i++){
    sum += asssociatedColumn[i];
  }
  return sum;
}

3.2 Unnecessary Expressions

Expressions should be stated in reduced expressions. The most common example we have seen throughout this course is in regards to boolean expressions. A good example and a bad example is demonstrated below.

// Suppose these declarations exist:
boolean booleanExpression1 = true;
boolean booleanExpression2 = false;

// Bad Example - Note redundancy
if (booleanExpression1 && booleanExpression2) {
  return true;
} else {
  return false;
}

// Good Example - All cases are expressed in a single statement
return booleanExpression1 && booleanExpression2