EasyBeans Code Convention Contributions should follow the EasyBeans code convention. A good document to begin with is Java code convention. Other conventions are also listed in this document. In addition, EasyBeans uses tools to check the compliance: the checkstyle plugin and the eclipse checkstyle plugin. The configuration settings are available in the Eclipse settings of the project.
File Organization
Header All files should have a header that contains the LGPL and the date. If a file is modified, the modification year should be appended to the existing year, which is the year it was initially created. For example, if the create date is '1999' or '2004' it should be edited to '1999-2006' or '2004-2006', respectively. Also, the tag $Id: code_convention.xml 314 2006-04-04 09:39:43Z pinheirg $ should be added. The following is a header example: /** * EasyBeans * Copyright (C) 2008 Bull S.A.S. * Contact: easybeans@ow2.org * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA * USA * * -------------------------------------------------------------------------- * $Id$ * -------------------------------------------------------------------------- */
Imports Imports should reference a valid class name, instead of using wildcard imports. Wildcard imports are not authorized. For example, if the interface and class List and ArrayList are used, the imports should not be as follows: import java.util.*; The imports should have each class as follow: import java.util.List; import java.util.ArrayList; The classes should not have an unused import. The Eclipse IDE provides facilities to do this job. There is the option Organize Imports (Shift+Ctrl+O) in the menu Source that correctly inserts the imports and removes the unused imports. However, this option does not work well with 'import static'.
Class and Interface Declarations The class and interface names should begin with an uppercase letter. Also, each class and interface has an @author tag in the comment. For example: /** * This is an example that shows a class/interface declaration. * @author Gisele Pinheiro Souza * @author Eduardo Studzinski Estima de Castro */ public class ClassExample implements InterfaceExample{ }
Indentation / WhiteSpace
Indentation The space character is used instead of the tab character. The number of spaces for an indent is 4 spaces. Wrapping a single source line into multiple lines should follow the Java code convention.
WhiteSpace Any trailing spaces should be removed. Eclipse provides a plugin that removes the trailing spaces and converts the tab into spaces. The plugin is AnyEdit. Use whitespaces in for() loop, while(), when concatenating strings. One space should be added before the operator and another after the operator. For example, the correct syntax is: for (int i = 0; i < arTest.length; i++) { String strResult = "The element " + i + " has the value " + arTest[i]; } The following code does not adhere to the convention: for (int i = 0; i< arTest.length; i++) { String strResult = "The element "+ i+" has the value "+arTest[i]; }
JavaDoc Comments All methods and attributes (including protected and private) must have a comment. The parameters, the exceptions thrown, and the method return should have a comment in the method comment. For example: /** * This is an example that is used in the EasyBeans Code Convention. */ private int intValue; /** * This is an example method to show a class comment. * @param a an example of parameter. * @param b other example of parameter. * @return the method result. * @throws Exception the exception thrown by the method. */ public int add(final int a, final int b) throws Exception { return a + b; }
If/else Braces must be used in the if/else blocks, even if there is a single statement. To illustrate: if (true) { doThis(); } The following is not allowed: if (true) doThis(); The position of the braces should be the same as in the first example. The following format is incorrect: if (true) { test1(); test2(); }
Try/catch All exceptions require a statement; no silent catching is allowed. For example: try { doThis(); } catch (Exception e) { // should not occur } A logger can be used: try { doThis(); } catch (Exception e) { logger.logDebug("Exception while doing .....", e); }
Inline Conditionals Inline conditionals are not allowed. The following code is incorrect: b = isOk() ? true : false; The correct way to write this is as follows: if (isOk()) { b = true; } else { b = false; }
Naming Conventions
Static Final Attributes Declarations are static final, not final static. This is a JLS recommendation.
Constants Constants should be static and final, and should adhere to the following: '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
No Magic Numbers, Use Constants Constants must be used in the code and magic number must be avoided. For example, the following is not allowed: private int myAttribute = 5; The correct format is:/** * Default value */ private static final int DEFAULT_VALUE = 5; /** * This attribute is initialized with the default value */ private int myAttribute = DEFAULT_VALUE;
Attribute Name The attribute name should not have an underscore ( _ ). The _ is valid for constants that are in uppercase. Use pValue and mValue instead of p_Value and m_Value. The pattern for attribute name is: '^[a-z][a-zA-Z0-9]*$'