CS685 Group Project Style Guide

• File Headers
• Comments
• Names
• Control Block Structure
• Miscellaneous

File Headers

• One class per file.

• Each file starts with a header. Headers should be in the following format:

  ////////////////////////////////////////////////////////////////////////////
  //
  // File: filename
  //
  // Purpose: description_of_module
  //
  // Authors:
  //   initial  full_name  email_address
  //
  // Modifications:
  //   06-DEC-1998  initials  brief_description_of_changes
  //   07-DEC-1998  initials  next_entry's_description
  //
  ////////////////////////////////////////////////////////////////////////////

• Here's an example:

  ////////////////////////////////////////////////////////////////////////////
  //
  // File: Module.java
  //
  // Purpose: Defines the Module class.  A Module consists of Design
  //          Parameters (DPs) or Functional Requirements (FRs).  For
  //          simplicity, we call FRs and DPs "Nodes".  The "Boss"
  //          Module (Module #0) contains the FRs.
  //
  // Authors:
  //   txe  Travis Emmitt  emmitt@virginia.edu
  //
  // Modifications:
  //   28-OCT-1998  txe  Initial creation
  //
  // Todo:
  //   comment methods
  //   remove unused methods
  //   add error handling: exceptions, warnings (debatable)
  //
  ////////////////////////////////////////////////////////////////////////////

• I like to have the Todo: section in there as a reminder and indicator of future plans, but it is not required.

Comments

• Do not use the "/* ... */" comment style. Use "//" instead.

• Comment each member variable in a class.

• Add comments before each method, or at the very least each public method.

• Add other comments as needed, at your discretion. If your QA reviewer asks for comments in particular sections, put 'em in.

• Example:

  ////////////////////////////////////////////////////////////////////////////
  //
  // File: House.java
  //
  // Purpose: This is a simple, untested class used to illustrate
  //          style guidelines.
  //
  // Authors:
  //   txe  Travis Emmitt  emmitt@virginia.edu
  //
  // Modifications:
  //   02-NOV-1998  txe  Initial creation
  //
  ////////////////////////////////////////////////////////////////////////////
  
  public class House {
    private int num_doors;          // number of doors
    private Color color;            // color of siding
  
    // This creates a new house with the specified number of
    // doors and siding color.
  
    public House (int n, Color c) {
      num_doors = n;
      color     = c;
    }
  
    // This changes the number of doors the house has.
  
    public void ChangeNumDoors (int new_num_doors) {
      if (new_num_doors < 0) {
        num_doors = 0;
      }
      else {
        num_doors = new_num_doors;
      }
    }
  }

Names

• variables_look_like_this
• MethodsLookLikeThis ()
• CONSTANTS_LOOK_LIKE_THIS

Control Block Structure

• Always use { and }, regardless of whether it's a one-line block or not.

• Put the { at the end of the opening line.

• Always begin the else or catch block on a line after the }. You can of course add more whitespace and comments in between.

• Example:

  if (new_num_doors < 0) {
    num_doors = 0;
  }
  else {
    num_doors = new_num_doors;
  }

Miscellaneous

• Chaining of constructors is OK within reason.

• All code must execute under UNIX. Use of deprecated functions is okay.

Version 3.0 - 14-DEC-1998 txe
Updated to 3.0, updated format, dates

Version 1.0 - 02-NOV-1998 txe
Initial creation