This is the end of the preview. Sign up
to
access the rest of the document.

Unformatted text preview: EE322C Java Coding Standards – Summer, 2009
Writing code that is easy for others (or you later) to read is an important part of programming. Style entails a program's readability and logic structuring. Style is almost as important as correctness in programming. This is useful for you, the programmer, when you are writing code and the graders for reading and making sense of a program. Also, in industry and real-world situations, you usually do not write a whole program at once, nor do you only look at programs you wrote. Usually industry programmers are looking at code they did not write or wrote a long time ago, which is where style and comments become very important to understanding programs. Here are the style rules for this course. Your program will be graded on conformance with these rules. Naming Conventions: 1. All programmer defined identifiers shall use names that are meaningful with respect to the real world concepts that they represent. (This includes class names, method names, variable names, constants, etc.) 2. The name of a variable shall help describe its purpose in the program and/or what it is an abstraction of from the real world. For example:
int numTokens; double hypotenuse; Although they are short names, it's ok to use x or y if they represent coordinates; or i and j for matrix or table indices (these are standard conventions in the real world). Otherwise use of single letter variables should be avoided. 3. Variable and method names should be in camel casing (lower case except for internal words whose first letter shall be capitalized and interior letters of method names and variables can be capitalized eg: numFirstSalary). Usually when two or more words are combined into one method name or variable name, we capitalize the internal words. No $ characters will be included in variable and method names. 4. 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. 5. 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_SIXTYFIVE. Associated constants (final variables) should be prefixed by a common type name. Ex: final int CODE_COLOR_RED = 1;
final int CODE_COLOR_GREEN = 2; final int CODE_COLOR_BLUE = 3; 6. Class names shall start with an uppercase letter and internal run-together words shall start with a capital. All other letters shall be lowercase. Examples:
public class Thing public void methodName() { } int numberOfElements = 35; final double PROPERTY_TAX_RATE = 0.014; Alignment and Indentation: 1. Braces must be lined up vertically. This includes braces for a class, a method, and braces that contain a code block for if/else statements. (The only times that braces may be lined horizontally are for blocks that contain a single line of code). 2. Statements in the same program block shall be lined up vertically. For example, this means all the statements in the main method must line up. 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. 3. 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 (3 spaces). This includes instance variable declarations and method headers. The header for the main (or any) method is indented one tab, as well as the braces for the main (or any) method. The program statements and code inside the main (or any) method shall be indented two tabs. Other blocks of code will be indented to visually show its level of nesting within the overall program logic structure. For example:
public class Thing { public static void main(String args) { int num = 3; if (num > 0) if (num < 10) num++; else num--; else num = 0; } // end of main }// end of Thing Other White space: Blank lines and white spaces improve readability by setting off sections of code that are logically related. Two blank lines should always be used in the following circumstances: 1. Between sections of a source file 2. Between class and interface definitions One blank line should always be used in the following circumstances: 1. 2. 3. 4. Between methods Between the local variables in a method and its first statement Before a block or single-line comment There shall be a space after keywords and surrounding all binary operators. Use of comments: 1. There should be a header comment block at the beginning of the class with the main program in it explaining the purpose and general operation of the whole program. The program header block should also contain the identify of the author (s), the course and section numbers, the assignment number, version number, date, and any other information necessary to identify the program. 2. Class comment blocks should contain the abstract data type (ADT) information describing what the class models in terms of the common attributes and behaviors of member objects of the class, and any key internal mechanisms. 3. Method comments should contain the ADT information describing the inputs, outputs, operation, pre and post conditions associated with that method. 4. Every other multi-line program block (i.e. enclosed in { } ) shall have a comment section explaining what it does. 5. The primary logic that reflects the algorithmic design of your program shall be embedded as comments throughout the code, so that it is visible and available for explanation. For example, your pseudocode or flowchart elements from your design are interspersed with the associated code. 6. single or partial line comments should use the form // this is a one line comment 7. multi-line comment blocks should use the form /* this is a block of comment lines with lots more stuff in there */ The program, class and method level comment blocks should be in javadoc format so that they can automatically be extracted into an html documentation format. Javadoc comments start with /** Ordering: Code within classes shall be in the following order: 1. public static final constants 2. private instance variables 3. public methods 4. private methods Prohibited constructs: 1. Use of the goto statement is prohibited. However, you may use the restricted forms of break; and continue; statements Other Common Practices (Not mandatory for this course) 1. Variables should be initialized where they are declared, and they should be declared in the smallest scope possible. 2. It is generally accepted to use the letters “ex” to represent Exceptions. 3. Complex conditional expressions should be avoided. Introduce temporary Boolean variables instead. 4. Type conversions should always be done explicitly. Never rely on implicit type conversion. ...
View Full
Document