[JBoss-dev] CVS update: newsite guidelines.jsp

2001-07-19 Thread Mad 

  User: schaefera
  Date: 01/07/19 18:14:36

  Modified:.guidelines.jsp
  Log:
  Added remarks to how JavaDoc reviews can be implemented.
  
  Revision  ChangesPath
  1.2   +7 -3  newsite/guidelines.jsp
  
  Index: guidelines.jsp
  ===
  RCS file: /cvsroot/jboss/newsite/guidelines.jsp,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- guidelines.jsp2001/07/20 01:02:08 1.1
  +++ guidelines.jsp2001/07/20 01:14:36 1.2
  @@ -65,7 +65,7 @@
   *   @see 
   *   @author  {full name}.
   *   @author  Marc Fleury
  -*   @version $Revision: 1.1 $
  +*   @version $Revision: 1.2 $
   *   
   *   
Revisions:
   *
  @@ -102,6 +102,10 @@
 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.
   
  +
  +  Please add JavaDoc to every method/class when you working on this page. 
When you are not 100% sure about
  +  what you read please enlose the changed lines into "" and 
"" to indicate what
  +  you changed and gave up for a review. When someone reviewed it just 
remove this marks, thanx.
 
   

  @@ -130,7 +134,7 @@
   *   @see 
   *   @author  {full name}.
   *   @author  Marc Fleury
  -*   @version $Revision: 1.1 $
  +*   @version $Revision: 1.2 $
   *   
   *   
Revisions:
   *
  @@ -256,7 +260,7 @@
   *   @see 
   *   @author  {full name}.
   *   @author  Marc Fleury
  -*   @version $Revision: 1.1 $
  +*   @version $Revision: 1.2 $
   *   Revisions:
   *
   *   
Revisions:
  
  
  

___
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development

[JBoss-dev] CVS update: newsite guidelines.jsp

2001-07-19 Thread Mad 

  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  ChangesPath
  1.1  newsite/guidelines.jsp
  
  Index: guidelines.jsp
  ===
  
  
  
   
  
  
  
  

DEVELOPER CODING GUIDELINES

  
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.
  
  
To see a template for a class file go to the JBoss-Source 
:/src/etc/class.java and for an interface:
/src/etc/interface.class.
  
  
  Layout
  
  

  
Identation: 3 Spaces (no Tabs because they look ugly in "dump" editors 
like HTML pages (online CVS) )
  
  
Comments: line up comments on the left hand side (also Javadocs)
  
  
Grouping: Group members, methods etc. according to the templates and use 
the template's comments to
separate them.
  

  
  
  General Code
  
  
The first part of a JBoss class should contain the Copyright comment:

  /*
  * JBoss, the OpenSource EJB server
  *
  * Distributable under LGPL license.
  * See terms of license at gnu.org.
  */

  
  
Next part is the package definition. Please use NO ABBREVIATIONS and 
follow the Java guidelines.
  
  
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).
  
  
Add the JavaDoc Documentation for the main class which looks like this:

  /**
  *    
  *
  *   @see 
  *   @author  {full name}.
  *   @author  Marc Fleury
  *   @version $Revision: 1.1 $
  *   
  *   
Revisions:
  *
  *   
mmdd author:
  *   
    
  *   
  •  explicit fix description (no line numbers but methods) go beyond the 
cvs commit message
  *   

  *eg: 
  *   
20010516 marc fleury:
  *   
    
  *   
  •  Ask all developers to clearly document the Revision, changed the 
header.  
  *   

  */

Instead of "@see" you can also use "{@link ...}" inside the comments (inline 
reference).
ALWAYS add these comments, the developer after you will love it and 
hopefully do his/her part as well.
  
  
  
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

  
When Parameter can or cannot be null and also what it means when null is 
allowed
  
  
When Return values can be or are never null
  
  
Document side effects
  
  
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.
  

  

  Coding a Class
  

  /*
  * 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
  
  /**
  *    
  *
  *   @see 
  *   @author  {full name}.
  *   @author  Marc Fleury
  *   @version $Revision: 1.1 $
  *   
  *   
Revisions:
  *
  *   
mmdd author:
  *   
    
  *   
  •  explicit fix description (no line numbers but methods) go beyond the 
cvs commit message
  *   

  *eg: 
  *   
20010516 marc fleury:
  *   
    
  *   
  •  Ask all developers to clearly document the Revision, changed the 
header.  
  *   

  */
  
  
  // DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS
  
  public class X
  extends Y
  implements Z
  {
 // Constants -
 
 // Attributes 
 
 // Static --