CS 307 Coding Standards
These standards are based on the Java Coding Standards. Writing code that is easy for others to read and modify is an important part of programming. Learning to program does not just mean getting the program to work. The program should be easy to read and understand. It should be decomposed as the problem itself is decomposed and solved. In the "real world" and on the later assignments you simply will not be able to write all the code at once. You will have to code in pieces and if you do not use good style you will spend a large amount of time asking yourself, "what was I trying to do here?" The following are the rules of style I can explain easily. There are others I cannot, such as a good decomposition or an elegant algorithm. In come cases I cannot define bad style, but I know it when I see it. Please remember that half of your assignment grade is based on the style of your program, which means following the standards below as well as making the program easy to understand.
Object variable and primitive variable names will be
meaningful. The name of variable shall help describe its purpose in
the program and / or what it is an abstraction of from the real world. Of
course you can go to far:
numberOfMembersOnTheOlympicTeam - too long
n - too short
numTeamMembers - just right
And of course some short variable names are used so much they have a clear
meaning even though they are very short
i, j, and k - loop counters
n, len, length - length of array or String
x, y - Cartesian coordinates
Variable and method names shall be lower case except for
internal words whose first letter shall be capitalized. No underscore
or $ characters will be included in variable and method names.
Constants shall be declared and used for all values in your
program that model real world constants or for numbers that are not to
change in the program. The only exceptions are when using the numbers
-1, 0, 1, and 2.
Constant names shall be meaningful and help describe what
the constant represents. The name shall be all capital letters with
underscore characters used to separate internal words. A good constant
name would be DAYS_PER_YEAR. A bad constant name would be
THREE_HUNDRED_SIXTY_FIVE.
Class names shall start with an uppercase letter and
internal words shall start with a capital. All other letters shall be
lowercase.
There shall be a space after keywords and surrounding all
binary operators.
Braces must be lined up vertically or horizontally.
This includes braces for a class, a method, and braces that contain a code
block for if/else statements. (The only time braces may be lined horizontally are for methods that contain
a single line of code).
Statements in the same program block shall lined up
vertically. To ensure this is correct no matter what editor is being
used to view your code use either all tabs or all spaces. Mixing tabs
and spaces may cause the code to look good in your editor, but it may look
bad in another editor if the tabs are set differently.
Code shall be indented to show the code block it belongs
to. For example other than the class header and class braces, all code
in a class shall be indented one tab. So the header for the main
method is indented one tab, as well as the braces for the main method.
The program statements and code inside the main method shall be indented two
tabs. Code shall be indented to show the code block it belongs
to. For example other than the class header and class braces, all code
in a class shall be indented one tab. So the header for the main
method is indented one tab, as well as the braces for the main method.
The program statements and code inside the main method shall be indented two
tabs.
Code in classes shall be in the following order:
| Part of Class/Interface Declaration | Notes | |
| 0 | import statements | |
| 1 | Class/interface documentation comment (/**...*/) |
See "Documentation Comments" on page 9 for information on what should be in this comment. (Note page 9 refers to a page from the Sun Java Coding Standards, not the required textbook of the class. Click on the link on the website to see the information on what to include in comments.) |
| 2 | class or interface
statement |
|
| 3 | Class/interface implementation comment
(/*...*/), if necessary |
This comment should contain any class-wide or interface-wide information that wasn't appropriate for the class/interface documentation comment. |
| 4 | Class (static) variables |
First the public class
variables, then the protected, then package level (no
access modifier), and then the private. |
| 5 | Instance variables | First public, then protected,
then package level (no access modifier), and then private. |
| 6 | Constructors | |
| 7 | Methods | These methods should be grouped by functionality rather than by scope or accessibility. For example, a private class method can be in between two public instance methods. The goal is to make reading and understanding the code easier. |
All private instance variables shall be prefixed
with my as in myBox or myDirection.
All private static variables will start with the prefix our
as in ourRandomNumGenerator.
private instance variables that are primitives shall start
with a prefix indicating the type of primitive:
y: byte
s: short
i: int
l: long
f: float
d; double
b: boolean
c: char
so if myDirection is a private instance variable with type integer the
correct name is iMyDirection
Leave a blank line after every method
Each class and method shall have a comment explaining what
it does. At a minimum comments for methods will list pre and post conditions.
The things that must be true when calling the method and the things that
will be true when the method is done assuming the preconditions were met.
The pre and post conditions should be stated in mathematical terms and in
terms of the public interface of the class whenever possible.
Booleans: Booleans are great and they add readability to a
program, but it helps to use them correctly. A lot of beginning programmers
use booleans in very awkward ways:
if (flag == true) // GACK!!
if (flag) // much better
if( matches > 0 )
found = true;
else
found = false; // DOUBLE GACK!!!
found = ( matches > 0 ); // so nice
if( hadError == false)
return true;
else
return false; // DOUBLE DOG GACK!!
return !hadError; // a thing of beauty