Computer Science 210
Data Structures

Fall 2016, Siena College

Home     Syllabus     Schedule     Examples     Style Guide

Style Guide for CSIS 210 Programs

The way you present your program is just as important as having a correct program. While having good comments or good variable names will not affect the correctness of your program, it will make it easier to read your program. It is important that others be able to understand your code so that they can modify your code if they have to. A significant component of your grade on programming assignments will be determined by your programming style.

This is a guide to help you better understand what we are looking for when we look at your programs. As the semester progresses there will be steeper penalties for styling mistakes. So get into the habit of writing good programs from the beginning. After writing your program, be sure to look over your code with the guidelines here in mind.

Commenting

Comments are extremely important. Take some care to write accurate yet concise comments.

• Be specific with your comments. What happens when the readDataFile method is called? What is the ArrayList used for? Your comments should describe the intent of the code. What are you trying to accomplish with this piece of code?
• Do not make your comments (or code) too wide. Any line of comment or code that is over 80 characters should be split up over several lines. If many lines in your program do not print nicely, we will find it difficult to read.
• Do not overcomment! Overcommenting can make the program hard to read just as much as under-commenting. Do not comment every line. If your instructions are simple and clear, most people will understand them without your comments. If you think you need commenting, try commenting chunks of code under the same comment.
• Delete any extraneous code. You would not hand in an English paper with crossed out lines. Similarly, you should not hand in a lab with commented out code. Remove all code that your program no longer uses.

You should write comments for:

• Class (Program): At the top of each class, you should write your name and a brief description of what the class is for. If you decide to do more than the assignment requested, you should describe these "extra" features in the program under the class description. Sometimes it's hard to tell a bug from a feature.
• Methods: Above each method heading there should be a brief description of what the method does. You should also describe what each parameter means and what the return result means. If the method code is simple you do not need to comment in the method body. If the method body is complicated, you might want to add some comments to certain areas that you deem to be complicated. Be careful not to overcomment!
• Variables and constants: In general, variables and constants should all have comments as to what the variable is used for. For example a good comment for your the variable

        private ArrayList<String> words;
  

  might be:

       // the list of words that form the dictionary for our program
  

  rather than, say,

       // words
  

  Frequently, several closely related variables or constants can be grouped together under the same comment.

Blank Lines

Blank lines are used to delineate different areas of the code. The instance variable declarations at the top of your program should be separated from the header of the class and the header of the first method. There should always be a blank line between methods. It is advisable to break up long method bodies and long declarations into logical pieces. Always start a new line after a semicolon.

Naming Literals

Do not use "magic numbers" in your method bodies. A magic number is a numeric constant embedded in code, without a constant definition. Any number except -1, 0, 1, and 2 should probably have a name that gives the number meaning (and even those numbers, sometimes). For example, rather than writing

        points = new Coords[10];

associate a static final variable with the number, defining a named constant:

        private static final int NUM_POINTS = 10;

and use the named constants in place of the numbers:

        points = new Coords[NUM_POINTS];

Names

You should always choose names that suggest the meanings of the things being named. If the purpose of a method is to remove all the blanks from a string, then a good name for that method is removeBlanks. If there is a variable of type int that is used to refer to the total number of turns left in a game, then a good name might be turnsLeft or remainingTurns.

Names that have nothing to do with the program are very bad names! For example:

    private PrintWriter c3po;

would be a poor name unless the PrintWriter happens to represent a shiny gold protocol droid with a British accent.

Names that are not specific or descriptive enough are generally bad names. For example:

   double a;

would not be descriptive at all.

Try not to name objects sequentially. You should only do this when the objects are related in some way that is not otherwise expressible. For example,

   JButton button1;
   JButton button2;
   JButton button3;

are not as good as startButton, pauseButton, and resetButton if they are being used to create buttons that start, pause, and reset a simulation, for example.

Naming Conventions

The Java compiler is quite flexible about the names given to identifiers like class names, instance and local variables, and named constants. However, by convention, Java programmers (including us) will follow these rules:

• class names: capitalize, if made up from more than one word, capitalize each word. e.g., BinaryTree, DecimalFormat, Scanner.
• instance variable, local variable, and method names: lower case, if made up from more than one word, capitalize all but the first word. e.g., nextInt, laundry, numLittleDots.
• named constants: all caps, if made up from more than one word, separate words by underscore characters. e.g., BALL_DIAMETER, VELOCITY, START_X.

Whenever possible, names should be declared as local variables rather than instance variables. Instance variables should only be used when a value must be saved for use after the execution of a method or constructor is completed.

Appropriate Use of Language Constructs

There are many instances where there are multiple correct ways to write a section of code. Often, there is little advantage to one over another. However, we will aim to use the most appropriate construct in those cases where one is more appropriate than another.

Loop Constructs

We will use three main loop constructs this semester: the while loop, the standard for loop, and the "for-each" variant of the for loop.

Guidelines: When waiting for some condition to become true, such as a value to exceed some limit, or for a valid file name to be entered, a while loop is most appropriate. For counting, a for loop is most appropriate. When iterating over all of the items in a collection such as an array or an ArrayList, either a standard or "for-each" style for loop is appropriate.

Conditionals

Programmers often write boolean expressions in conditionals and loop constructs that are based on the value of a boolean variable. For example:

  if (numberEntered == true) {
      // do something
  }

or

  while (done == false) {
     // do something
  }

These are error-prone practices, as even highly experienced programmers could mistakenly write:

  if (numberEntered = true) {
      // do something
  }

or

  while (done = false) {
     // do something
  }

Normally, Java complains if you use an assignment operator where you meant to use a comparison for equality in a boolean expression. But in this case, since the assignment is to a boolean variable, the assignment itself evaluates to a boolean and is perfectly valid Java. But think about what's happening here. The if statement will always execute the "do something" block, since the statement both sets numberEntered to true and evaluates to true. In the while loop, the body of the loop can never execute, since done will be set to false and the condition will evaluate to false.

Better way to write these that are both more concise and which avoid these potential problems:

  if (numberEntered) {
      // do something
  }

or

  while (!done) {
     // do something
  }

Assigning a boolean Variable

Another common code pattern that should be avoided is the following:

  if (someBooleanExpression) {
      booleanVar = true;
  }
  else {
      booleanVar = false;
  }

While there is nothing incorrect about the above, it can be written much more concisely (and to generate more efficient code), as follows:

  booleanVar = somebooleanExpression;

Formatting

Your program should be formatted as neatly as possible. The statements and declarations placed in a method's body should be indented a few spaces more than the method's header. Similarly, the bodies of while loops and if statements should be indented slightly compared to the headers of these constructs. Sequences of statements that do not contain if statements, while loops or other control constructs should all be indented by the same amount.

BlueJ makes indentation easy to fix: select "Auto-Layout" from the "Edit" menu when you are editing a Java file and it will indent your code nicely.