CS5 Coding Conventions

It is very important to use good and consistent coding conventions. They tend to make code more readable both for yourself and others (including your TA). For this reasons, it is in your best interest that all assignments meet the standards described below. That and the fact that a portion of your grade will be based on how well you followed the conventions.
By now you should be familiar with all of the below terms.

Naming Conventions

Packages

Example: ComputerScience
Packages are groups of classes that make up an application. The name of the package will usually be the name of the program you are writing. Package names should begin with a capital letter and all new words within the name should start with a capital letter.

Classes

Example: TeachingAssistant
Object classes should be named using nouns which describe what the class models. Class names should begin with a capital letter and all new words within the name should start with a capital letter.

Methods

Example: gradePrograms()
These usually perform some kind of action and/or return a value, so we use verbs to indicate what they do. Method names should start with a lowercase letter and all new words within the name should start with a capital letter.

Local Variables

Example: numStudentsInClass
Local variable names should be comprised of nouns describing the information they store. All local variable names begin with a lowercase letter and each new word begins with a capital letter.

Instance Variables

Example: favoriteCheese_ or _favoriteCheese
Instance variables should follow the same conventions as local variables, except they should have underscores either at the end or at the beginning of the variable name (pick one and be consistent!). Since instance variables are declared outside of the methods in which they are used, it is often helpful to distinguish them from local variables.

Constants

Example: PAY_RATE
Constants should have names consisting of nouns describing their content. In order to distinguish them from other variables, we use only capital letters in their names and separate different words with underscores.

Please try to avoid variable and method names that consist only of one letter, or are otherwise non-descriptive. Something like myVar.myMethod(a) provides absolutely no useful information. And that's bad.

Commenting

Comments should be used for adding imformation to your code. Your comments should not just repeat the code that you have written! Comments should be added whenever an explanation or clarification is needed for some section or line of code, such as a difficult sequence of commands, an unusual or atypical design pattern, or a very brief synopsis of what a particular method call might do or return. If you are not sure whether or not to comment a line of code, comment it anyway.

Helpful Hint: Comment as you go along, do not leave all your commenting until the end of the project. The last thing anyone wants to do after they get their program working is go back and comment.

Header Comments

Header comments describe methods and classes. They consist of a block of information placed before the code they explain. Every Class must have a Header Comment. Use multiline commenting style (/**...*/) for header comments. You should describe each class and it's design in the header comment. Remember to put your name and your account number at the top of each file. Your Applet class should contain a header comment that describes the design of the entire program. Here you should also indicate if your program has any bugs in it.

Example:

/**
* Class: Smurf
* Package: SmurfVillage
* This class models a generic Smurf. It contains references to a
* SmurfHead, arms, legs, and a hat, because all of those are
* parts of a Smurf, and should be contained within the Smurf
* class. This is the superclass that will be used for the other
* Smurf classes (eg. PapaSmurf, HandySmurf, etc). Most of the
* code for the Smurf methods will be in this class, to avoid
* repeating it in the subclasses.
*/

Every method should also have a header which contains a comment describing its purpose and how it achieves its purpose and a list of variables passed to and/or modified by the method. If the method returns a value or takes parameters, this should be described in the header as well. The more detailed the description, the better.

Example:

/**
* Method: performSmurfMagic
* class: Smurf
* Parameter: MagicItem - the item needed to do the magic
* This is the default performSmurfMagic method. Since all smurfs
* are able to perform a little magic,this method need not be
* changed in the subclasses. Only the PapaSmurf class, which can
* perform magic better than your average Smurf, will need to
* redefine this method.
*/

Glossary Comments

Glossary comments explain the purpose of each constant and variable, and should only appear when it is unclear why a certain variable is needed. They appear to the right of the identifier they describe. If the comment does not fit to the right of the iden tifier, it should be on the line immediately above the identifier. In a list of identifiers, glossaries should be left or right aligned for easier reading. Use // commenting style for glossaries.

Example:

public class CSFive extends ComputerScienceClass {

private Professor professor_; //Professor for the class
private int studentsInClass_; //number of students
...

Inline Comments

Inline comments appear in code clarifying its workings. Use // commenting style for inline comments. Lines should be commented to describe what they are doing. Note that this comment should not just repeat what the Java code does, but sho uld elaborate on the code. This should be done for every section and logical chunk of code.

Examples:
time++; //add one to time <- Useless
time++; //update clock to current hour <- Useful

Last Modified: 05:02pm EDT, August 17, 1997