User: schaefera Date: 01/07/19 18:02:08 Added: . guidelines.jsp Log: Guidelines web site to explain this and make it easier to read. Revision Changes Path 1.1 newsite/guidelines.jsp Index: guidelines.jsp =================================================================== <jsp:include page="head.jsp" flush="true" /> <jsp:include page="slogan.jsp" flush="true" > <jsp:param name="SLOGAN" value="CONTRIBUTE TO JBOSS: Guidelines"/> </jsp:include> <!-- CONTENT --> <p class="head">DEVELOPER CODING GUIDELINES</p> <p class="text"> This Guidelines are here to make the JBoss code more readable. Because of the "Age" of JBoss there will be always some code around which does not follow the guidelines but over time this may become less and less. </p> <p class="text"> To see a template for a class file go to the JBoss-Source :<jboss>/src/etc/class.java and for an interface: <jboss>/src/etc/interface.class. </p> <p class="head">Layout</p> <p class="text"> <ul> <li> Identation: 3 Spaces (no Tabs because they look ugly in "dump" editors like HTML pages (online CVS) ) </li> <li> Comments: line up comments on the left hand side (also Javadocs) </li> <li> Grouping: Group members, methods etc. according to the templates and use the template's comments to separate them. </li> </ul> </p> <p class="head">General Code</p> <p class="text"> The first part of a JBoss class should contain the Copyright comment: <pre> /* * JBoss, the OpenSource EJB server * * Distributable under LGPL license. * See terms of license at gnu.org. */ </pre> </p> <p class="text"> Next part is the package definition. Please use <b>NO ABBREVIATIONS</b> and follow the Java guidelines. </p> <p class="text"> Now add the external classes import statement. Please use always fully qualified imports (no *) because then everyone knows which class comes from which package. When you have a conflict then import none or the best one and fully qualify the other class(es) when you use them (example: java.util.Date and java.sql.Date). </p> <p class="text"> Add the JavaDoc Documentation for the main class which looks like this: <pre> /** * <description> * * @see <related> * @author <a href="mailto:{email}">{full name}</a>. * @author <a href="mailto:[EMAIL PROTECTED]">Marc Fleury</a> * @version $Revision: 1.1 $ * * <p><b>Revisions:</b> * * <p><b>yyyymmdd author:</b> * <ul> * <li> explicit fix description (no line numbers but methods) go beyond the cvs commit message * </ul> * eg: * <p><b>20010516 marc fleury:</b> * <ul> * <li> Ask all developers to clearly document the Revision, changed the header. * </ul> */ </pre> Instead of "@see" you can also use "{@link ...}" inside the comments (inline reference). <b>ALWAYS add these comments, the developer after you will love it and hopefully do his/her part as well</b>. </p> <p class="text"> Document all public (and mostly protected) members and methods in the class with JavaDoc except you did not add new functionality during overwriting a method (comming from an Interface or a base class). Especially note <ul> <li> When Parameter can or cannot be null and also what it means when null is allowed </li> <li> When Return values can be or are never null </li> <li> Document side effects </li> <li> Usefull is also when you mention if and where another method or the overwritten method is called. Because this is open-source it is not that important but when you only rely on the documentation it can avoid endless calls or other avoid mistakes when you have to call the overwritten method. </li> </ul> </p> <p class="head">Coding a Class</p> <p class="text"> <pre> /* * JBoss, the OpenSource EJB server * * Distributable under LGPL license. * See terms of license at gnu.org. */ package x; //EXPLICIT IMPORTS import a.b.C1; // GOOD import a.b.C2; import a.b.C3; // DO NOT WRITE import a.b.*; // BAD /** * <description> * * @see <related> * @author <a href="mailto:{email}">{full name}</a>. * @author <a href="mailto:[EMAIL PROTECTED]">Marc Fleury</a> * @version $Revision: 1.1 $ * * <p><b>Revisions:</b> * * <p><b>yyyymmdd author:</b> * <ul> * <li> explicit fix description (no line numbers but methods) go beyond the cvs commit message * </ul> * eg: * <p><b>20010516 marc fleury:</b> * <ul> * <li> Ask all developers to clearly document the Revision, changed the header. * </ul> */ // DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS public class X extends Y implements Z { // Constants ----------------------------------------------------- // Attributes ---------------------------------------------------- // Static -------------------------------------------------------- // Constructors -------------------------------------------------- // Public -------------------------------------------------------- public void startService() throws Exception { // Use the newline for the opening bracket so we can match top and bottom bracket visually Class cls = Class.forName(dataSourceClass); vendorSource = (XADataSource)cls.newInstance(); // JUMP A LINE BETWEEN LOGICALLY DISCTINT **STEPS** AND ADD A LINE OF COMMENT TO IT cls = vendorSource.getClass(); if(properties != null && properties.length() > 0) { try { } catch (IOException ioe) { } for (Iterator i = props.entrySet().iterator(); i.hasNext();) { // Get the name and value for the attributes Map.Entry entry = (Map.Entry) i.next(); String attributeName = (String) entry.getKey(); String attributeValue = (String) entry.getValue(); // Print the debug message log.debug("Setting attribute '" + attributeName + "' to '" + attributeValue + "'"); // get the attribute Method setAttribute = cls.getMethod("set" + attributeName, new Class[] { String.class }); // And set the value setAttribute.invoke(vendorSource, new Object[] { attributeValue }); } } // Test database vendorSource.getXAConnection().close(); // Bind in JNDI bind(new InitialContext(), "java:/"+getPoolName(), new Reference(vendorSource.getClass().getName(), getClass().getName(), null)); // We are done log.log("XA Data source "+getPoolName()+" bound to java:/"+getPoolName()); } // Z implementation ---------------------------------------------- // Y overrides --------------------------------------------------- // Package protected --------------------------------------------- // Protected ----------------------------------------------------- // Private ------------------------------------------------------- // Inner classes ------------------------------------------------- } </pre> </p> <p class="head">Coding a Interface</p> <p class="text"> <pre> /* * JBoss, the OpenSource EJB server * * Distributable under LGPL license. * See terms of license at gnu.org. */ package x; //EXPLICIT IMPORTS import a.b.C1; // GOOD import a.b.C2; import a.b.C3; // DO NOT WRITE import a.b.*; // BAD /** * <description> * * @see <related> * @author <a href="mailto:{email}">{full name}</a>. * @author <a href="mailto:[EMAIL PROTECTED]">Marc Fleury</a> * @version $Revision: 1.1 $ * Revisions: * * <p><b>Revisions:</b> * * <p><b>yyyymmdd author:</b> * <ul> * <li> explicit fix description (no line numbers but methods) go beyond the cvs commit message * </ul> * eg: * <p><b>20010516 marc fleury:</b> * <ul> * <li> Ask all developers to clearly document the Revision, changed the header. * </ul> */ // DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS public interface X extends Y { // Constants ----------------------------------------------------- // Static -------------------------------------------------------- // Public -------------------------------------------------------- public ReturnClass doSomething() throws ExceptionA, ExceptionB; } </pre> </p> <jsp:include page="navigation.jsp" flush="true" /> _______________________________________________ Jboss-development mailing list [EMAIL PROTECTED] http://lists.sourceforge.net/lists/listinfo/jboss-development