Style Guide for CS 139
This Style Guide should be used as a reference for all work turned in
for credit, both labs and programming assignments. It is
based on standard java coding guidelines. See http://developers.sun.com/sunstudio/products/archive/whitepapers/java-style.pdf
for a complete java guide.
Names - All
names should be descriptive and readable. subTotal rather
than s, grade rather than grd. Multiple word names
should use
either a Capital letter or underscore (_) to separate words (not both).
subTotal or sub_total.
- Variable and method names should begin with a small letter.
subTotal
-
Variable names should be noun phrases (studentName
or subTotal)
- Method names should be verbs or verb phrases (print_line or addColumn)
- Class names should begin with a capital letter and use
title case. HelloWorld.
- Constant names should be all caps with an underscore
separator. PI, INTEREST_RATE.
Declarations - Where and when to declare variables
- All variables and constants should be declared at the top of the method or class in which they are used.
- Each declaration should be on its own line. Comment to the right if the name is not self explanatory.
- Group declarations by type and put them in alphabetical order by type and within type by name.
- Variables should be declared at the top of the method or class and instantiated in the body of the code when needed.
- Constants should be declared and initialized at the top of the method or class.
Indentation - Provides
a visual structure for your program.
- Sub sections of code should be
indented a consistent 3 spaces for readability.
- Blocks of code surrounded by curly braces should have the
curly braces line up vertically and the open brace should line up
directly beneath the first letter of the header for that block.
- Statements which are too long for the line should be
indented 3 spaces for the 2nd and more lines.
Operators
- Binary operators should be separated from their operands by a
single space on either side. Unary operators should not have
a space.
- Ex: sum = myGrade + yourGrade; myGrade++;
- An exception is the dot (.) operator which does not have space surrounding it. Ex: System.out.println();
Structure
- One line of white space should follow the declaration of variables.
- Use white space to separate segments of code.
- In a class declaration, constructors should
precede all other methods, then the methods should be in order by
visibility modifier then alphabetically within the same modifier..
- Lines should be kept to a short length (<80).
You should be able to see the full line in your editor and in the
submit system.
Comments
- Comments provide a guide to what the program is doing.
- Must come before the code that they are describing or if brief on the same line.
- In-line comments (//) should describe major structures or steps
within a method.
- Block comments(/* */) should describe each class and method.
- Should use normal English spelling and grammar.
Phrases are okay.
Header - every
source file must contain the following in its header.
/***************************************************************************
* Overall
description of the class goes here
*
* @author Your
name goes here
* @version Vn -
date
*
Description of the assignment (ex: Lab1, PA1 - Mile
conversion)
***************************************************************************/
Programming
Assignments - Every programming assignment
must contain the following statement or must cite any sources used
(such as a TA).
/***************************************************************************
* References and
Acknowledgements: I received no outside help with this
* programming
assignment
*
***************************************************************************/
OR
/***************************************************************************
* References and
Acknowledgements: TA Glenn helped me with the foo method.
*
***************************************************************************/
Methods
- All methods must contain a header which contains the following if
applicable. Make sure that you do not give
an @param or @return tag for methods that take no parameters or which
do not return a value.
/***************************************************************************
* Overall
description of the method goes here
*
* @param
paramterName Describe each input parameter, must have one @param line
for each
*
@return Describe the value that this method returns.
*
Description of the assignment (ex: Lab1, PA1 - Mile
conversion)
***************************************************************************/
Miscellaneous
- Methods should have a single return statement if it is a value returning method.
- You may not use the break statement except for within the switch statement.
- All class variables should be private unless there is a documented reason for not doing so.
- All class constants should be public unless there is a documented reason for not doing so.
- All visibility modifiers should be explicitly stated.