Computer Science Style Guide

General Comment

As in all writing, the use of whitespace, separators, and formatting is very important. Remember, you almost never write code just for yourself. Other people are going to read and modify your code. Try to make it as easy as possible for them.


Commenting Your Code

  1. File Header Comment

    A file header comment that fully describes the project and purpose of the code is placed at the top of every .java source code file. A programmer (or non-programmer for that matter) should be able to read the header comment and understand the high level idea or purpose behind the code, as well as the data-structures and methods that are used.

    The file header comment contains the following information:

    /********************************************************
     *
     *  Project :  <Name of project|assignment>
     *  File    :  <Name of source code file>
     *  Name    :  <Name of programmer>
     *  Date    :  <Date created (project due date)>
     *
     *  Description : (Narrative desciption, not code)
     *
     *    1) What is the purpose of the code; what problem does the code solve.
     *
     *    2) What data-structures are used.
     *
     *    3) What algorithms, techniques, etc. are used in implementing the data structures.
     *
     *    4) What methods are implemented (optional).
     *
     *  Changes :  <Description|date of modifications>
     *
     ********************************************************/
    
  2. Method Header Comment

    Each method should have a separate header comment that describes the algorithm implemented by the method without forcing the reader to interpret the code. The method header also serves to visually separate each method. Remember, the use of whitespace and good formatting styles is as important in coding as in writing technical papers.

    The method header also allows you to use fewer comments in the code segment of the method, thus making it cleaner and more readable.

    Related short methods or dummy methods may be grouped under one header describing them all.

    Here is an example of a good method header.

    /****************************************************
     * Method     : Sort
     *
     * Purpose    : The Sort method sorts an array of
     *              integers using a standard bubble sort.
     *              The array is sorted in place.
     *
     * Parameters : array              - an array of integers
     *              number_of_elements - the number of elements
     *                                   in the array
     *
     * Returns    : This method does not return a value.
     *
     ****************************************************/
    
    void sort ( int[] array, int number_of_elements )
    {
      ...;
    }
    
  3. Source Code Comments

    If you do something clever that is not obvious to everyone else, add a comment to briefly describe what you have done. Do not comment every line! This will only make your code unreadable to you and everyone else. If you are not doing something tricky then the code should be able to tell the story for you.

    For example:

      if ( !empty )
      {
        head.value = tail.prev.count * 3;
        tail = head.prev;   // make circular
      }
      else
      {
        // what follows is a single line of code to replace
        // an if..else statement; basically, assign head to
        // whichever direction tail points
        head = (tail.left != null) ? tail.left : tail.right;
      }
    
    

Formatting Your Code

  1. Indentation

    The proper use of indentation will make your code 100% more readable. Select a TAB setting of no more than four (4) characters and indent as you code to make sure things are properly aligned. All statement inside a block should be indented one tab (see example below). To allow for different tab settings for different editors, always use the tab key for indentation - never use the space bar.

  2. Aligning Curly Braces {}

    Aligning paired {} vertically for maximum readability is very important. Regardless of the style used in text or other reference books, or any other coding styles you may be familiar with, aligning paired {} vertically is the standard for all CS programming courses.

    Here is a sample code snippet that illustrates the proper placement of {} and how statements inside a block are all aligned by indenting one (1) tab. NOTE: Notice how the variable names make reading the code confusing!

    int function ( int x, float y )
    {
      double d = 100.0;
      int abbra = x * y,
        x2 = y,
        a;
    
      while( ( d < ( abbra + y ) ) && ( a != "b" ) )
      {
        if( x < y )
        {
          return a ;
        }
        else
        {
          x += "l";
        }
      }
      return abbra;
    }
    
  3. Identifier Naming Conventions

    The following standard Java naming conventions should be followed:
    • Choose identifiers that accurately describe the nature of the data stored in the variable.
    • Each word in a class name is capitalized:
      class SalariedEmployee
    • The first word in a variable or method name is all lower case, each additional word in the identifier is capitalized:
      double taxRate;
      double calculateParkingCharges( double hours )
    • Constants (final variables) are all upper case; if the identifier consists of more than one word, separate each word with an underscore (_);
      final int MAX_SIZE = 100;

Adapted from a style guide used at the Univeristy of Utah.