fet ep coding guideline 20110625

(Draft) Coding Convention

New eProcurement xxx-xxx-xxxxxx

1. 1 1

1. ...................................................................................................2 2. .........................................................................................................6 3. ...................................................................................................7 3.1 DB ...........................................................................................7 3.2 ..........................................................................................7 3.3 Package .............................................................................8 3.4 Class & Interface ............................................................10 3.5 Variable........................................................................................10 3.6 Method.........................................................................................11 4. ..........................................................................................12 4.1 ...............................................................................................12 4.2 ........................................................................................12 4.3 ........................................................................................12 4.3.1 Indentation...................................................................12 4.3.2 Package Import...................................................................12 4.3.3 Line Length..................................................................13 4.3.4 ....................................................................................13 4.3.5 .....................................................................................13 4.3.5.1 Block Comments..........................................14 4.3.5.2 Single-Line Comments..................................15 4.3.5.3 Trailing Comments........................................15 4.3.5.4 Documentation Comments...........................16 SpringMVC - Controller ..................................................18 4.3.5.5 SpringMVC - Method ...........................................19 4.3.5.6 Service ................................................................21 4.3.6 Declarations.................................................................24

4.3.6.1 Number Per Line....................................24 4.3.6.2 Initialization.....................................................24 4.3.6.3 Placement.................................................24 4.3.6.4 Class and Interface Declarations.....25 4.3.7 Statements..................................................................25 4.3.7.1 Simple Statements.......................................25 4.3.7.2 Return Return Statements...................................26 4.3.7.3 if, if-else, if else-if else Statements............................26 4.3.7.4 for Statements...........................................................28 4.3.7.5 while Statements.......................................................28 4.3.7.6 do-while Statements..................................................28 4.3.7.7 switch Statements.....................................................29 4.3.7.8 try-catch Statements.................................................29 4.3.8 White Space.................................................................30 4.3.8.1 Blank lines.......................................................30 4.3.8.2 Blank Spaces................................................30 4.3.9 Native SQL Statement.........................................................30 5. Programming Practices.........................................................................31 5.1 Providing Access to Instance and Class Variables........................31 5.2 Referring to Class Variables and Methods....................................31 5.3 Constants.....................................................................................31 5.4 Variable Assignments...................................................................31 6. Miscellaneous Practices........................................................................32 6.1 Hinbernate Lazy-Loading..............................................................32 6.2 Parentheses..................................................................................32 6.3 Returning Values..........................................................................32 6.4 Expressions before ? in the Conditional Operator........................33 7. Special Comments................................................................................33 4 36

7.1 Framework Related.......................................................................33 7.2 Others..........................................................................................34 8. Logging.................................................................................................34 9. Opensource Libraries............................................................................35 10. ...............................................................................................36

2. eProcurement

3.3.1 DB : : :

DB Table __ EP_ECT_COMMODITIES EP_SYS_PARAMETERS ERP_ITEM_MASTER EP_ECT_COMMODITIES_S

Sequen ce

3.3 Package Supplier Portal eCatalog OSP PR PO RFQ RFX RPT RR SQ VPE Controller com.fet.ep.external.web.controller.msb com.fet.ep.external.web.controller.validator.msb com.fet.ep.internal.web.eCatalog com.fet.ep.internal.web.controller.osp com.fet.ep.external.web.controller.validator.osp com.fet.ep.internal.web.controller.pr com.fet.ep.external.web.controller.validator.pr com.fet.ep.internal.web.controller.po com.fet.ep.external.web.controller.validator.po com.fet.ep.internal.web.controller.rfq com.fet.ep.external.web.controller.validator.rfq com.fet.ep.internal.web.controller.rfx com.fet.ep.external.web.controller.validator.rfx com.fet.ep.internal.web.controller.rpt com.fet.ep.external.web.controller.validator.rpt com.fet.ep.internal.web.controller.rr com.fet.ep.external.web.controller.validator.rr com.fet.ep.internal.web.controller.sq com.fet.ep.external.web.controller.validator.sq com.fet.ep.internal.web.controller.vpe com.fet.ep.external.web.controller.validator.vpe Service com.fet.ep.service com.fet.ep.service.i mpl Persistence com.fet.ep.dao.msb com.fet.ep.dao.impl.msb com.fet.ep.dao.eCatalog com.fet.ep.dao.osp com.fet.ep.dao.impl.osp com.fet.ep.dao.pr com.fet.ep.dao.impl.pr com.fet.ep.dao.po com.fet.ep.dao.impl.po com.fet.ep.dao.rfq com.fet.ep.dao.impl.rfq com.fet.ep.dao.rfx com.fet.ep.dao.impl.rfx com.fet.ep.dao.rpt com.fet.ep.dao.impl.rpt com.fet.ep.dao.rr com.fet.ep.dao.impl.rr com.fet.ep.dao.sq com.fet.ep.dao.impl.sq com.fet.ep.dao.vpe com.fet.ep.dao.impl.vpe Entity com.fet.ep.dao.entity.msb com.fet.ep.dao.entity.eCatal og com.fet.ep.dao.entity.osp com.fet.ep.dao.entity.pr com.fet.ep.dao.entity.po com.fet.ep.dao.entity.rfq com.fet.ep.dao.entity.rfx com.fet.ep.dao.entity.rpt com.fet.ep.dao.entity.rr com.fet.ep.dao.entity.sq com.fet.ep.dao.entity.vpe

Security

com.fet.ep.internal.web.controller.security com.fet.ep.external.web.controller.validator.secur ity com.fet.ep.batch com.fet.ep.integration

com.fet.ep.dao.security com.fet.ep.dao.impl.securit y com.fet.ep.dao.batch com.fet.ep.dao.impl.batch com.fet.ep.dao.integration com.fet.ep.dao.impl.integra tion

com.fet.ep.dao.entity.securit y com.fet.ep.dao.entity.batch Com.fet.ep.dao.entity.integra tion

Batch Integratio n

3.4 Class & Interface Class & Interface (_)(-)( Java ) Expression[^A-Z][0-9a-zA-Z]* class : Controller : , Controller , : PRController Service Interface : , Service , : PRService Service Implementation: Service, Impl , : PRServiceImpl DAO Interface: , Dao , : PrDao DAO Implementation: , DaoImpl , : PrDaoImpl Entity: , EP_ , EP_PR, Entity PR Abstract Class Class Abstract

3.5 Variable Data, Member () (_)(-)( Java )

Expression[^A-Z][0-9a-zA-Z]* Variable, Parameter Data Member Iteration Counter i k m j l n (prefix): String : s (Example : sEmployeeCode) StringBuffer : sb (Example : sbSQLQuery) Date : d (Example : dToday) boolean : is (Example : isSuccess) byte : bt char : ch int : i (Example : iCount) long : l float : f double : dn (Example : dnExchangeRate) ArrayList/List : lt (Example : ltQueryResult) Hashtable : ht HashMap/Map : hm (Example : hmUserProfiles) HashSet/Set : hs Object : ao (Example : aoResultSet, aoXMLFile, etc.) Constant (_) (-) Expression[^A-Z] ([0-9a-zA-Z]|_|-)*

3.6 Method Method JavaBeans Conventions , : PRService.createPR, PRDao.findByRequestor 11 36

() (_)(-)( Java ) Expression[^A-Z] ([0-9a-zA-Z]|_|-)* Constructor Class

4.4.1 Sun Sun Java Code Conventions

4.2 2000 JAVA class interface. class interface File class interface class interface File

4.3 4.3.1 Indentation 4 tab tab IDE tools tabs ( CVS) 4.3.2 Package Import package import Import import class interface 12 36

(*) package class interface importclassjava.*javax.* import

package com.client_name.ep.bo.Order; import java.util.Properties; import java.util.Vector

4.3.3 Line Length 80 4.3.4 / Eclipse (SeedConvention.xml) {} || $WorkerThread = getThreadFactory().newThread($RUN_LOOP) { $WorkerThread.start(); } else { // notify(); // }

if ($WorkerThread == null

4.3.5 code

Java Sun Java Code Convention /** * Title: com.client_name.ep.bo.Order * Description: Business Object of Order * Copyright: (c) Copyright IBM Corp. 2006. All Rights Reserved. * Company: IBM GBS Team * @author Jimmy Chen * @version 1.0 * Change history * 2006-11-01 Add field [Approver] by Billy Tsai * 2006-11-31 Update [Approver] type to string by Jimmy Chen */

4.3.5.1 Block Comments /**- reformat indented

someMethod();

/* * Start Employee Query. Here is a block comment. */ queryEmployee();

/* End - Employee Query. */

4.3.5.2 Single-Line Comments indented /*...*/ // (Trailing Comment) (Block Comment) if (condition) {

handleCondition(); // Handle the condition //handleConditionOld(); /* Start Employee Query. Here is a block comment. */ queryEmployee(); /** End - Employee Query. */ }

4.3.5.3 Trailing Comments // indented if (i == 2) { return true; } else { return false; } 15 36 // Explain why here

// special case

4.3.5.4 Documentation Comments Document JAVA classinterfaceconstructormethode field Document /***/ class/interface/method Document indented 80 method JavaDoc inline comments /** * Graphics is the abstract base class for all graphics contexts * which allow an application to draw onto components realized on * various devices or onto off-screen images. * A Graphics object encapsulates the state information needed * for the various rendering operations that Java supports. This * state information includes: *

The Component to draw on *

A translation origin for rendering and clipping coordinates *

The current clip *

The current color *

The current font *

The current logical pixel operation function (XOR or Paint) *

The current XOR alternation color * (see setXORMode) *

* * All coordinates which appear as arguments to the methods of this * Graphics object are considered relative to the translation origin * of this Graphics object prior to the invocation of the method. * All rendering operations modify only pixels which lie within the * area bounded by both the current clip of the graphics context * and the extents of the Component used to create the Graphics object. * * @author * @author * @version * @since Sami Shaio Arthur van Hoff %I%, %G% 1.0 16 36

New eProcurement xxx-xxx-xxxxxx */ public abstract class Graphics { /** * Draws as much of the specified image as is currently available * with its northwest corner at the specified coordinate (x, y). * This method will return immediately in all cases, even if the * entire image has not yet been scaled, dithered and converted * for the current output device. * * If the current output representation is not yet complete then * the method will return false and the indicated * {@link ImageObserver} object will be notified as the * conversion process progresses. * * @param img * @param x * * @param y * * * * @return * * * @see * @see * @since */ public abstract boolean drawImage(Image img, int x, int y, ImageObserver observer); the image to be drawn the x-coordinate of the northwest corner of the destination rectangle in pixels the y-coordinate of the northwest corner of the destination rectangle in pixels of the image is converted. May be null true if the image is completely loaded and was painted successfully; false otherwise. Image ImageObserver 1.0

* @param observer the image observer to be notified as more

/** * Dispose of the system resources used by this graphics context. * The Graphics context cannot be used after being disposed of. * While the finalization process of the garbage collector will

New eProcurement xxx-xxx-xxxxxx * also dispose of the same system resources, due to the number * of Graphics objects that can be created in short time frames * it is preferable to manually free the associated resources * using this method rather than to rely on a finalization * process which may not happen for a long period of time. * * @see * @see * @see * @see * @see * @since */ public abstract void dispose(); /** * Disposes of this graphics context once it is no longer * referenced. * * @see * @since */ public void finalize() { dispose(); } } #dispose() 1.0 #create(int, int, int, int) #finalize() Component#getGraphics() Component#paint(Graphics) Component#update(Graphics) 1.0

SpringMVC - Controller SpringNVC Controller Controller Controller Controller

Controller

SD Controller

SD /** * * * */ Public Class MySampleController{ }

4.3.5.5 SpringMVC - Method method SpringMVC method request mapping SpringMVC Controller method Controller method request mapping URL method SD /Link

method /** * * * * */ @RequestMapping() Public ModelAndView myViewAction(){ }

4.3.5.6 Service Service Service Service Service Interface Implementation InterfaceService Class Level Method Level

Service Class Level service /** * * * * */

Service Method Level method pre-conditions post-conditions/** * * * * * * * pre-conditions * * * * * * post-conditions * * * * * *

/** * * PRLine * PRLinePOPO PRLine * PRLinePRLine * ERPPR_LINE_IDPR LINE * * pre-conditions * PRHeader"(3)" * PRLine"(2)" * PRLine0 * * post-conditions * 1)POPRLinesplit * 2) * 2.1)PRLine"(3)" * 2.2)budget control record insBudgetPurItem * 2.3)ERP * 3) * 3.1)PRLine"(3)"(PO) * 3.2)budget control record insBudgetPurItem, changeBudgetAmount * 3.3)PRLine"(2)"(-PO ) * 3.4)budget control record addBudgetLine * 3.5)ERP, splitErpReqItem * 4)PR Tx Log * * @param prLineId * * * PR_LINE_ID PRPOPO_LINE_ID * @param poLineId * @param trfQuantity * @param actorNum

New eProcurement xxx-xxx-xxxxxx * * @return * */ @Transactional(propagation=Propagation.REQUIRED) public void buyerTrfPrLineToPO(Long prLineId, Long poLineId, BigDecimal trfQuantity, String actorNum) throws BusinessRuleException; N/A BusinessRuleException

* @exception

4.3.6 Declarations 4.3.6.1 Number Per Line Sun Java Code Conventions // Indentation level // Size of table

int iLevel; int iSize;

int iPageNo, iIdx; // AVOID Object currentEntry;

4.3.6.2 Initialization 4.3.6.3 Placement block for indexes for statement for indexes for statement

int int1 = 0; if (condition) { int int2 = 0; // ... } int int3 = 0; // int1 //

void myMethod() {

4.3.6.4 Class and Interface Declarations '(' '{' '}' '}' '{' int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ... }

class Sample extends Object {

4.3.7 Statements 4.3.7.1 Simple Statements statement

i++; j++;

i++; j--; // if(calculate(i++, ++j).otherMethodCall()) { } // AVOID

4.3.7.2 Return Return Statements return 4.3.7.3 if, if-else, if else-if else Statements if statement {} if statement if statement {..} /* * if */ if (condition){ // statements; } // /* * if */ if (condition) {

New eProcurement xxx-xxx-xxxxxx // statements; } else { // statements; } // /* * if */ if (condition){ // statements; } else if (condition) { // // /* * if */ if(condition2) { // statements; } } else { //

statements; }

statements;

if (condition)

4.3.7.4 for Statements for for for /* * for */ for (initialization; condition; update){ statements; }

for (initialization; condition; update);

4.3.7.5 while Statements while while /* * */ while (condition){ statements; } while

while (condition);

4.3.7.6 do-while Statements do-while do 28 36

New eProcurement xxx-xxx-xxxxxx /* * */ do { statements; } while (conditions) do

4.3.7.7 switch Statements case break case switch case /* * */ switch(i) { case 1 : // case 2 : // break; default : // break; }

4.3.7.8 try-catch Statements try-catch try { statemetns; } catch(ExceptionClass e){ statements }

try-catch-finally

New eProcurement xxx-xxx-xxxxxx statements; } catch(ExceptionClass e){ statements; } finally { statements; }

4.3.8 White Space 4.3.8.1 Blank lines methods local variables (block comment)(single-line comment)

4.3.8.2 Blank Spaces method(commas) forstatements(separated)

4.3.9 Native SQL Statement SQL Native SQL PL/SQL Developer SQL

5.Programming Practices5.1 Providing Access to Instance and Class Variables instancepublic public membersSDCoding

5.2 Referring to Class Variables and Methods objectstaticclass classMethod(); // ok AClass.classMethod(); // ok anObject.classMethod(); // AVOID

5.3 Constants ()1,0,-1constants

5.4 Variable Assignments ch1 = ch2 = 'c'; // AVOID

if (c++ = d++) { // AVOID

d = (a = b+c) + r; // AVOID

6.Miscellaneous Practices6.1 Hinbernate Lazy-Loading Hibernate ORM Hibernate Lazy-Loading associated-class performance impact Hibernate Lazy-Loading

associated-class Hibernate one-to-oneone-to-many many-to-one DAO associated-class

List prLineItems = prMaster.getLineItems();

List prLineItems = PRDAO.getLineItems(prMaster.getID());

6.2 Parentheses if (a == b && c == d) // AVOID if ((a == b) && (c == d)) // USE this

6.3 Returning Values 32 36

New eProcurement xxx-xxx-xxxxxx // AVOID if (booleanExpression) { return true; } else { return false; } // USE this return booleanExpression; // Other expression return (condition ? x : y);

6.4 Expressions before ? in the Conditional Operator ? : Condition/Statement ? : (x >= 0) ? x : -x;

7.Special Comments7.1 Framework Related ServiceDAO ServiceBusiness Logic(: ControllerDAOStored Procedures, etc.) CacheI/O while(condition) { queryEmployee(); // AVOID } Hashtable htEmployee = queryAllEmployee(); // OK Java ClassProperties (Java Class, JSP, etc.) Web UI

7.2 Others methodJavaDoc classjava documentauthor true/false (Sun Java Code Conventions 10.5.2 ) full nameclassimport java.util.Datejava.sql.Date 15 StringBuffer String null pointer assignment null stringcontentreference== String referenceString content, String.compareto String.equals methods String.equals() String String null FileNotFoundException Exception final static assignments expression expression compiler code resourcesfileresource, JVMgarbage collectionfinalize resourcelock

8.Logging Logfile logDB log File logBusiness Logic 34 36

DB log 1. DB log 2. SessionDB log 3. DB log & file log log4jfile logRuntime log level INFO DEBUG System.outlog File log6House Keeping DB log6Archiving

log message Method log.debug Method log.debug exception log.error exception stack trace if..then..else 10 log.debug for log.debug

9.Opensource Libraries Opensource Libraries Name Spring Version 3.05 Comments

Hibernate MyBatis Sitemesh

3.51 3.03 2.42

3. SQL

4. ( 80 method) JavaDoc + inline comments

5. Class JavaDoc Class

Sun Code Conventions for the Java Programming Language

fet ep coding guideline 20110625

Documents