foundation/eclipselink.core.test/src/org/eclipse/persistence/tools/refactoring/CodingStandard.java

/*******************************************************************************
 * Copyright (c) 1998, 2013 Oracle and/or its affiliates. All rights reserved.
 * This program and the accompanying materials are made available under the 
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 
 * which accompanies this distribution. 
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Oracle - initial API and implementation from Oracle TopLink
 ******************************************************************************/  
package org.eclipse.persistence.tools.refactoring;

// no blank line here - first specify Java imports:
import java.lang.reflect.*;
// blank line - next specify all the TopLink imports:
import org.eclipse.persistence.sessions.*;
import org.eclipse.persistence.exceptions.*;
// another blank line
/**
 * <p><b>Purpose</b>: Describe the purpose of the Class.
 * <p><b>Responsibilities</b>:<ul>
 * <li> class responsibility
 * <li> class responsibility
 * </ul>
 *
 *  @author ABC
 *  @since TOPLink/Java 1.0
 */
// yet another blank line
public class CodingStandard {
// still another blank line
    /** Put one line comment describing the following variable */
    protected String giveDescriptiveNameToVariables;
    
    /** Put one line comment describing the following variable */
    protected String useTabsToIndentVariables;
    
    /** Put one line comment describing the following variable */
    protected String useSingleLineSpacingBetweenVariables;

    /** Put one line comment describing the following variable */
    protected String commentShouldBeJustBeforeVariable;

    /** Put one line comment describing the following variable */
    protected String useSpacingAfterAndBeforeClassOpenAndCloseBrackets;

    /** Put one line comment describing the following variable */
    protected String allVariablesAreProtected;
    
    protected String commentOnlyImportantVariables;
    // final blank line
    /**
     * First of all, we should not access variables directly in the methods. 
     * But if we do then always use this.attributeName notation.
     */ 
    public void accessingClassAttributes() 
    {

    }
    
    /**
     * 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
     */ 
    public void blankLines() 
    {
    
    }
    
    /**
     * 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);
     *
     */
    public void blankSpaces() 
    {

    }
    
    /**
     * 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);
     *              }                   
     */ 
    public void booleanVariable() 
    {

    }
    
    /**
     * 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.
     */ 
    public void declarationsInTheMethod(Session firstArgument, String secondArgument)
    { /* Place the starting bracket on a new line */
      /* One declaration per line is recommended since it encourages commenting */
        int level,      // indentation level
            size;       // size of table
        /* New declaration should start on new line */
        float foo,
              bar;
        /* Give one line space before coding method body */
        methodBody();       
    }
    
    /**
     * Never break for-statements into multiple lines.
     * Break down the components of the for-statement into multiple lines if necessary.
     */  
    public void forStatements()
    { 
        /* WRONG 
         * The following loop puts too much information on the same line:
         *
         * for (Enumeration mappings = getQuery().getDescriptor().getMappings().elements(); mappings.hasMoreElements(); ) {
         *      some statements;
         *  }
         *
         */
    
        /* RIGHT
         *
         *  Vector mappings = getQuery().getDescriptor().getMappings();
         *  for (Enumeration mappingsEnum = mappings.elements(); mappingsEnum.hasMoreElements(); ) {
         *      some statements;
         *  }
         *
         */
    }
    
    /**
     * 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();
     */  
    public void ifElseStatements()
    {
        boolean condition = true;
    
        if (condition) {
            //statements
        }
    
        if (condition) {
            //statements
        } else {
            //statements
        }

        if (condition) {
            //statements
        } else if (condition) {
            //statements
        } else {
            //statements
        }
    }
    
    /**
     * Avoid long statements. Maintainence is a nightmare.
     */ 
    public void longStatements()
    {
        /*
         * WRONG:
         * setTableDefinition(getTableDefinitionNamed(((DatabaseTable)getMapping().getDescriptor().getTables().firstElement()).getName()));
         *
         * RIGHT:
         * The right approach to this statement would be to break it up into smaller statements. This would mean few more
         * lines and local variables, but will be easy to understand
         *
         * DatabaseTable table = (DatabaseTable)getMapping().getDescriptor().getTables().firstElement();
         * String tableName = table.getName();
         * TableDefinition tableDefinition = getTableDefinitionNamed(tableName);
         * setTableDefinition(tableDefinition);
         */
    }
    
    /**
     * 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.
     */  
    public void methodBody()
    {
        longStatements();
        ifElseStatements();
        forStatements();
        whileStatements();
        tryCatchStatements();
    }
    
    /**
     * INTERNAL:
     * Give a full description of the user callable method. Make sure it is javadoc compatible.
     * - blank line -
     * @param argument1 This is optional, give full description only if neccessary.
     * @exception InvocationTargetException This is optional, give full description only if neccessary.
     * @return String This is optional, give full description only if neccessary.
     */
    public String methodCommentsForNonAPI(String argument1, String argument2)
        throws IllegalAccessException, IllegalArgumentException, InvocationTargetException
    {
        String descriptiveVariable = "The variable should be descriptive enough to convey its meaning.";
    
        return descriptiveVariable;
    }
    
    /**
     * PUBLIC:
     * Give a full description of the user callable method. Make sure it is javadoc compatible.
     *  - blank line -
     * @param argument1 This is optional, give full description only if neccessary.
     * @exception InvocationTargetException This is optional, give full description only if neccessary.
     * @return String This is optional, give full description only if neccessary.
     */
    public String methodCommentsForUserAPI(String argument1, String argument2)
        throws IllegalAccessException, IllegalArgumentException, InvocationTargetException
    {
        String descriptiveVariable = "The variable should be descriptive enough to convey its meaning.";
    
        return descriptiveVariable;
    }
    
    /**
     * method comments
     */
    public void methodDeclarationIsLong(String argument1, String argument2)
        throws IllegalAccessException, IllegalArgumentException, InvocationTargetException
    {
        // do something
    }
    
    /**
     * method Comments
     */
    public void methodDeclarationIsReallyLong(
            String argument1,
            String argument2,
            String argument3,
            String ifYouHaveMoreArgumentsThenCheckYourMethod)
        throws
            IllegalAccessException,
            IllegalArgumentException,
            InvocationTargetException
    {
        // do something
    }
    
    /**
     * 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.
     */
    public void setAccessor(String useTabsToIndentVariable)
    {
        this.useTabsToIndentVariables = useTabsToIndentVariable;    
    }
    
    /**
     * 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.
     */  
    public void toplinkExceptions () throws DatabaseException, QueryException
    {
        /*
        Cursor cursor = prepareCuror();
        try {
            if (cursor.isEmpty()) {
                throw new QueryException("This must not be empty because ...", getQuery());
            }
            doStuff(cursor);    
        } catch (RuntimeException exception) {
            cursor.close();
            throw exception;
        }   
        */  
    }
    
    public void tryCatchStatements ()
    {
        /*
        try {
            statements;
        } catch (Exception exception) {
            statements;
        }   
        */  
    }
    
    public void whileStatements ()
    {
    /*
     * A while statement should have the following form:
     *              while (condition) {
     *                  statement;
     *              }
     *
     * An empty while statment should have the following form:
     *              while (condition);
     */
    }
}