oracle.toplink.tools.refactoring
Class CodingStandard

java.lang.Object
  |
  +--oracle.toplink.tools.refactoring.CodingStandard

public class CodingStandard

extends java.lang.Object

Purpose: Describe the purpose of the Class.

Responsibilities:

• class responsibility
• class responsibility

Since:

TOPLink/Java 1.0

Constructor Summary

CodingStandard()

Method Summary

Type	Method
void	accessingClassAttributes() First of all, we should not access variables directly in the methods.
void	blankLines() A blank line should always be used in the following circumstances: - between logical sections inside a method - to improve readability - between the method comment and the method declaration
void	blankSpaces() Blank spaces should always be used in the following circumstances: - A keyword followed by a parenthesis should be separated by a space: while (true) { ...
void	booleanVariable() A boolean variable should always be prefixed with conjunctions like is, has, does, should, etc.
void	declarationsInTheMethod(java.lang.String firstArgument, java.lang.String secondArgument) It's a good idea to declare all the varibles at the beginning of a code block as variables defined in the middle of the block can be confusing.
void	forStatements() Never break for-statements into multiple lines.
void	ifElseStatements() Always use the braces {}.
void	longStatements() Avoid long statements.
void	methodBody() NOTE: A compound statement is a statement that contains several other statements enclosed in braces "{}".
java.lang.String	methodCommentsForUserAPI(java.lang.String argument1, java.lang.String argument2) PUBLIC: Give a full description of the user callable method.
void	methodDeclarationIsLong(java.lang.String argument1, java.lang.String argument2) method comments
void	methodDeclarationIsReallyLong(java.lang.String argument1, java.lang.String argument2, java.lang.String argument3, java.lang.String ifYouHaveMoreArgumentsThenCheckYourMethod) method Comments
void	setAccessor(java.lang.String useTabsToIndentVariable) Instead of prefixing the parameter "useTabsToIndentVariable" with an article (e.g.
void	toplinkExceptions() TopLink exceptions are all runtime exceptions - so they do not have to be caught.
void	tryCatchStatements()
void	whileStatements()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CodingStandard

public CodingStandard()

Method Detail

accessingClassAttributes

public void accessingClassAttributes()

First of all, we should not access variables directly in the methods. But if we do then always use this.attributeName notation.

blankLines

public void blankLines()

A blank line should always be used in the following circumstances: - between logical sections inside a method - to improve readability - between the method comment and the method declaration

blankSpaces

public void blankSpaces()

Blank spaces should always be used in the following circumstances: - A keyword followed by a parenthesis should be separated by a space: while (true) { ... } - Note that a blank should not be used between a method name and its opening parenthesis. This helps to distinguish keywords from method calls. - Blanks should appear after commas in argument lists. - All binary operators should be separated from their operands by spaces. - The expressions in a "for" statement should be separated by blanks. for (expr1; expr2; expr3) - Casts should be followed by a blank. (void) method((byte) aNum, (Object) x);

booleanVariable

public void booleanVariable()

A boolean variable should always be prefixed with conjunctions like is, has, does, should, etc. Examples: isNullAllowed, shouldMaintainCache, doesObjectExist, hasTables The get accessor for such variables should be the name of the variable itself and the set accessor is the usual one Example isNullAllowed(), setIsNullAllowed(boolean value) With each boolean variable we should also provide two modifiers. Example allowNull() { setIsNullAllowed(true); } dontAllowNull() { setIsNullAllowed(true); }

declarationsInTheMethod

public void declarationsInTheMethod(java.lang.String firstArgument,
                                    java.lang.String secondArgument)

It's a good idea to declare all the varibles at the beginning of a code block as variables defined in the middle of the block can be confusing.

forStatements

public void forStatements()

Never break for-statements into multiple lines. Break down the components of the for-statement into multiple lines if necessary.

ifElseStatements

public void ifElseStatements()

Always use the braces {}. This makes the statement more clear and prevents some sloppy bugs (i.e if you add a second line). WRONG: if (condition) doStuff(); else doOtherStuff();

longStatements

public void longStatements()

Avoid long statements. Maintainence is a nightmare.

methodBody

public void methodBody()

NOTE: A compound statement is a statement that contains several other statements enclosed in braces "{}". The enclosed statements should be indented one more level than the compound statement. The opening left brace should be at the end of the line beginning the compound statement, and the closing right brace should begin a line and be indented to match the beginning of the compound statement. Braces are used around all statements, even single statements, when they are part of a control structure, such as an "if-else" or "for" statement. This makes it easier to add or delete statements without accidentally introducing bugs due to forgetting to add braces.

methodCommentsForUserAPI

public java.lang.String methodCommentsForUserAPI(java.lang.String argument1,
                                                 java.lang.String argument2)
                                          throws java.lang.IllegalAccessException,
                                                 java.lang.IllegalArgumentException,
                                                 java.lang.reflect.InvocationTargetException

PUBLIC: Give a full description of the user callable method. Make sure it is javadoc compatible. - blank line -

Parameters:

argument1 - This is optional, give full description only if neccessary.

Returns:

String This is optional, give full description only if neccessary.

Throws:

java.lang.reflect.InvocationTargetException - This is optional, give full description only if neccessary.

methodDeclarationIsLong

public void methodDeclarationIsLong(java.lang.String argument1,
                                    java.lang.String argument2)
                             throws java.lang.IllegalAccessException,
                                    java.lang.IllegalArgumentException,
                                    java.lang.reflect.InvocationTargetException

method comments

methodDeclarationIsReallyLong

public void methodDeclarationIsReallyLong(java.lang.String argument1,
                                          java.lang.String argument2,
                                          java.lang.String argument3,
                                          java.lang.String ifYouHaveMoreArgumentsThenCheckYourMethod)
                                   throws java.lang.IllegalAccessException,
                                          java.lang.IllegalArgumentException,
                                          java.lang.reflect.InvocationTargetException

method Comments

setAccessor

public void setAccessor(java.lang.String useTabsToIndentVariable)

Instead of prefixing the parameter "useTabsToIndentVariable" with an article (e.g. a, an, the) and then assigning to the class attribute we can do the following assignment. NOTE: Prefixing parameters in non accessor methods makes sense because we can differentiate between local variables and passed parameters.

toplinkExceptions

public void toplinkExceptions()
                       throws DatabaseException,
                              QueryException

TopLink exceptions are all runtime exceptions - so they do not have to be caught. If the method throws the exception then it must be declared in the "throws" clause. The one exception is if a runtime exception is caught for cleanup purposes, then it should not be re-thrown. A method that calls a method that throws a TopLink exception should not also throw it, the exception to this is database and optimistic lock exceptions which must always be thrown up to the user callable methods.

tryCatchStatements

public void tryCatchStatements()

whileStatements

public void whileStatements()