Java Program

lwoooudd3

codingstandards.pdf

Home >Computer Science homework help >Java Program

Regis CC&IS CS210 Coding Standards

Coding standards improve the readability of the software, allowing programmers to understand code more

quickly and thoroughly. Therefore, you will be required to follow the coding standards below when

writing Java code for CS210. Similar standards will be used in your next course, CS310.

Formatting

 Spacing:

 A blank space will appear after each comma (e.g. in argument lists, etc) in your code.

 Arithmetic, relational, and logical operators (e.g. +, *, <=, &&) must be separated from their

operands by spaces (one space before and one space after the operator).

 Unary operators (such as ++) will not be separated from their operands by any spaces.

 Each line should contain only one Java statement.

 One or two blank lines should be used to separate the logical sections of code and methods.

 Indentation:

 Four spaces will be used as the unit of indentation (this is the NetBeans default).

 Code lines will not extend past 80 characters (use the red line in NetBeans for reference).

Any lines that are longer than 80 characters will be broken into two or more lines.

 When breaking up code into multiple lines, break after a comma or before an operator.

The second and subsequent lines in wrapped code must be indented.

 Braces:

 Each open brace { can appear either:

 at the end of the same line that begins the statement

 on a line by itself, directly under the line that begins the statement

However, you must choose one of the above methods, and use it consistently.

 Each closing brace } should appear on a line by itself, directly underneath its corresponding

opening statement keyword.

 Use of opening and closing braces within decision and loop statements that contain only a

single statement is not required. But braces may still be used to help prevent errors.

Naming Conventions

 All identifiers (names) must be descriptive, meaningful, and reflect their usage.

The only single letter names that may be used are i and j as counters in for loops.

 The following formats will be used for identifiers:

 Classes

CapitalizedWithInternalWordsAlsoCapitalized (i.e. camelCase) – nouns

Example: StudentRegistration

 Methods

firstWordLowerCaseButInternalWordsCapitalized() (i.e. camelCase) – verb phrases

Example: enrollStudent()

 Constants (finals)

UPPER_CASE_WITH_UNDERSCORES – nouns

Example: MAX_STUDENTS

 Local and Instance Variables

firstWordLowerCaseButInternalWordsCapitalized (i.e. camelCase)

Example: studentIdNum

 Minimize the scope of constants and variables within your code.

They should not be defined in a scope outside the scope in which they are actually used.

Constant Usage

 Predefined constants will be used when they are available. For example, java.lang.Math defines a

large group of numeric constants, including PI and the exponential constant E.

 Local constants will be declared at the top of the method in which they are used, before any other

executable statements or variable declarations.

 Class-level constants (static or not) will be declared at the top of the class in which they are used,

before any instance variables.

 Meaningful constants will be used to represent literal values that have a meaning, because using

numeric literals makes code more difficult to read, understand, and edit.

NOTE: Defining symbolic constants for the values 0 and 1, unless they have a special meaning,

is not necessary.

Example (uses numeric literal): double taxCharged = purchaseAmount * 0.075; // uses numeric literal

Better (uses symbolic constant): final int TAX_RATE = 0.075; // uses symbolic constant

double taxCharged = purchaseAmount * TAX_RATE;

Use symbolic constants only when they improve the readability and maintainability of the code.

When the intent of the literal is obvious, using symbolic constants can impair code readability.

Example (unnecessary use of constant): final int DOUBLE_VALUE = 2;

numDoubled = num * DOUBLE_VALUE;

 Constant expressions will be used when the values they express are related.

Example: final int CURRENT_YEAR = 2015;

final int NEXT_YEAR = 2016; // does not show relation

would be better as: final int CURRENT_YEAR = 2015;

final int NEXT_YEAR = CURRENT_YEAR + 1; // expression shows relation

Variable Usage

 Use of global variables is prohibited.

 Global variables are variables that have been declared outside the method in which they

are used.

 Local variables are variables that have been declared inside a method.

 Instance variables are private data fields within a class.

ALL of your variables must be local variables or instance variables, , defined one per line.

 Variables will be initialized at the time they are declared, whenever possible.

Use of break, continue, and return statements

 The break statement may be used only to terminate a series of statements within a case of the switch statement. The break statement may never be used to terminate a loop.

 The continue statement may not be used anywhere within your code.

 A return statement will never be used to exit a loop. And ideally, every method shall converge on one return statement. The only exception to this rule is when extra return statement(s) are

used to return error codes that will end the program.

 An exit() call will never be used to exit a loop. And ideally, every method should exit via the normal return mechanism (whether implemented explicitly as a return statement, or executed

implicitly when a method ends) at the end of the main method. The only exception to this rule is

when an exit() statement is used to end a program due to an error that would prevent its

execution.

Use of more advanced Java code

 Programs for this course should use only the concepts covered in this course.

 Use of more advanced Java concepts and code will not be permitted.

Classes

 Within any main class, the main method will be defined first, before any other methods.

 Classes used to create objects will maintain the following ordering for definitions:

instance variables (data fields) first, then constructor(s), followed by setters and getters.

All other instance methods will appear below these methods, grouped by functionality.

Comments

 Comments should follow the indention structure of the code being commented.

 Use in-line comments to clarify non-obvious code. Comments should describe what is happening and how it is being done. Comments that simply parrot the code are of no value.

Don't add comments to obvious code – and try to make code obvious, so you don’t need too

many comments!

Example (unclear code with a comment):

int index = -1; // -1 serves as flag meaning the index isn't valid

would be better as (clearer code that does not need comment):

final int INVALID_INDEX = -1;

int index = INVALID_INDEX;

 Documentation of classes and methods

Class and method comments should support JavaDoc. JavaDoc comments will not be positioned

inside a method or constructor definition block. These comments will be placed above the class or

method header, and will be enclosed within the following markers /**

Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.

Both class and method comments should begin with a description of the class/method, followed

by a blank line and then tags.

These default NetBeans comments will be removed from your files. /*

* To change this license header, choose License Headers in Project Properties.

* To change this template file, choose Tools | Templates

* and open the template in the editor.

Class comments should minimally include a tag for the author and version, like this: @author xx // Full name (first & last), not username

@version xx, Assn X

Method comments should minimally include a tag for each parameter (if any)

and for the return value (if not void), like this: @param xx – description of xx

@return yy – description of yy

Later, after Topic 13, you will also add a tag for any method that throws an exception, like this: @exception exception thrown

Files

 Each Java source file shall contain a single public class.

 Files will have the following order: Beginning comments, package (if used) and import statements, class declarations.

 The filename will match the class name, appended by .java

(See the example code on the next two pages for examples of documented code files)

In file MainClass.java:

/* Top of file comments about overall program

* Include a complete description of what the program will do.

import java.xxx.*;

/** MainClass – Description of MainClass

* @author Firsname Lastname // include full name (no usernames)

* @version x, Java Assn #

public class MainClass {

/** main

* Description of what main method does

* @param args – describe the command line arguments (if used by program)

public static void main(String[] args) {

final int MAIN_CONSTANT = 5; // description of constant,

// if not obvious from name

int mainIntVar; // description of variable, if not obvious

// Inline comments will explain code that needs clarification

MyClass myObject = new MyClass(mainIntVar);

}

/** method1 - Description of value returning method1

* @param a - Description of a, if name not obvious

* @param b - Description of b, if name not obvious

* @return c - Description of c, if name not obvious

public static int method1(int a, int b) {

int c; // description, if name not obvious

// Example of breaking a long line of code to multiple lines

// (must indent subsequent lines, after first line)

System.out.println("The result of this method will be accomplished "

+ " by something being computed with " + c);

return c;

}

/** method2 - Description of void method2

* @param x - Description of x

public static void method2(int x) {

// Inline comments only needed to clarify code beyond the obvious

}

In file MyObjectClass.java (used when object classes are implemented -- from Topic 10 forward):

/** MyObjectClass – description of MyObjectClass

* Complete description of what object is being modeled

* and how the class will be used.

* @author Firstname Lastname

* @version x, Java Assn #

public class MyObjectClass {

// list data fields (attributes of object) at top of class

private int myIntField; // description, if name not obvious

private double myFloatField; // description, if name not obvious

/** MyObjectClass constructor // constructor(s) after data fields

* @param initialIntValue

* @param initialFloatValue

public MyObjectClass(int initialIntValue, double initialFloatValue) {

myIntField = initialIntValue;

myFloatField = initialFloatValue;

}

/** setMyIntField

* @param myIntField

public void setMyIntField(int myIntField) { // getters and setters next

this.myIntField = myIntField;

}

/** getMyFloatField

* @return myFloatField

public double getMyFloatField() {

return myFloatField;

}

// all other instance methods should be listed AFTER the constructor(s),

// getters, and setters

/** instanceMethod1 - Description of what instanceMethod1 does

* (example of method with a parameter and a return value)

* @param inputValue – Description of inputValue

* @return calculatedValue - Description of calculatedValue

public int instanceMethod1(int inputValue) {

int calculatedValue;

return calculatedValue;

}

/** instanceMethod2 - Description of what instanceMethod2 does

* (example of method with multiple parameters, but no return value)

* @param num1 - Description of num1, if name not completely explanatory

* @param num2 - Description of num2, if name not completely explanatory

public void instanceMethod2(int num1, int num2) {

}

/** instanceMethod3 - Description of what instanceMethod3 does

* (example of method with no parameters or return value)

public void instanceMethod3() {

}