site/src/site/xdoc/community/process/code-standards.xml - directory-project - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <document>
   <properties>
     <author email="akarasulu@apache.org">Alex Karasulu</author>
     <title>Apache Directory Project: Coding Standards</title>
   </properties>
 <body>
 <section name="Coding Standards">
  <p>This document describes a list of coding conventions that are required
  for code submissions to the project. By default, the coding conventions
  for most Open Source projects should follow the existing coding conventions
  in the code that you are working on. For example, if the bracket is on
  the same line as the if statement, then you should write all your code
  to follow that convention.</p>

 <p><strong>Please follow these conventions closely. It makes life so much
 easier.</strong></p>

 <p>Brackets should begin and end on a new line. Examples:</p>
 <source>

 if( foo )
 {
     // code here
 }

 try
 {
     // code here
 }
 catch( final Exception bar )
 {
     // code here
 }
 finally
 {
     // code here
 }

 while( true )
 {
     // code here
 }

 </source>

 <p>The preference is to include extra spaces between parenthesis and expression.
 For example;
 </p>
 <source>

 if( foo )

 </source>
 <p>4 spaces. <strong>NO</strong> tabs. Period. We understand that a lot of you like
 to use tabs, but the fact of the matter is that in a distributed development
 environment, when the cvs commit messages get sent to a mailing list, they
 are almost impossible to read if you use tabs.</p>

 <p>In Emacs-speak, this translates to the following command:</p>

 <source>(setq-default tab-width 4 indent-tabs-mode nil)</source>

 <p>In vim, having the following in your .vimrc will help:</p>
 <source>
 set tabstop=4
 set expandtab
 set list
 set listchars=tab:&gt;.
 </source>

 <p>Unix linefeeds for all .java source code files. Other platform specific
 files should have the platform specific linefeeds.</p>

 <p>Javadoc <strong>SHOULD</strong> exist on all your methods. Also, if you are working
 on existing code and there currently isn't a javadoc for that method/class/variable
 or whatever, then you should contribute and add it. This will improve the
 project as a whole.</p>

 <p>The Jakarta Apache/Directory License <strong>MUST</strong> be placed at the
   top of each and every file.</p>

 <p>If you contribute to a file (code or documentation), add the following author tag to the
 top of the file. For .java files the preferred Javadoc format is:</p>

 <source>
 @author &lt;a href="mailto:dev@directory.apache.org"&gt;Apache Directory Project&lt;/a&gt;
 </source>

  <p>Indent comments on an 80 column basis and the code on a
  100 column basis, using two more indents when a line must be wrapped.</p>

 <p>We focus on readability over performance, at least initially. Source code
 optimization is the last thing to be done to increase performance.
 If the code is not performing then it is better to re-engineer it rather
 than to expand loops, take out variable declarations etc. When the code
 is stable and has a well defined purpose and interface it may be appropriate
 to do source code optimization.</p>

 <p>Try to javadoc all methods and variables, especially public, protected
 and default access methods and member variables. Also add code comments
 when you think it's necessary (like assumptions).</p>

 <p>Variables are declared in the inner scope.</p>

 <source>
 while( myListIterator.hasNext() )
 {
     final String myString = (String)myListIterator.next();
 }
 </source>

 <p>Variables should be descriptive and ideally English words. The exceptions
 being loop counters (usually use i, j and k), exceptions (use concatenation
 of word separating characters - i.e. SocketException is abbreviated as se) and
 other commonly used abbreviations (i.e. sb for StringBuffer).</p>
 <source>
 try
 {
     for( int i = 0; i &lt; 10; i++ )
     {
         // some stuff
     }
 }
 catch( final FileNotFoundException fnfe )
 {
     // some stuff
 }
 catch( final IndexOutOfBoundsException ioobe )
 {
     // some stuff
 }
 </source>
 <p>
 Use String concatenation except in extremely performance sensitive
 sections. This leaves StringBuffer optimization to the compiler.
 So use:</p>
 <source>
 final String myString = "test " + "for " + "performances";
 </source>
 <p>Try not to declare a method as 'synchronized'.  If a method accesses
 a shared resource then surround accesses to that resource with
 a synchronized block. Ideally the synchronized block should surround
 the smallest possible area. For example:</p>
 <source>
 public void sharedMethod()
 {
     String display = null;

     synchronized( this )
     {
         display = mySharedObject.getHelloWorld();
     }

     System.out.println( display );
 }
 </source>
 <p>If you are within a static method, then you may have to create
 a static object whose sole purpose in life is to provide the
 lock you need. Alternatively you could use the Class object for
 the class you are in. That is, if you're in class MyClass, use
 "MyClass.class".</p>
 <p>Have the names of all member instance fields start with the prefix "m_".
 Example:</p>

 <source>
 class MyClass
 {
     Class m_class = MyClass.class;
     int m_users;
 }
 </source>

 <p>Don't chain method calls. The below:</p>
 <source>
 Thing thing = (MyThing)myObject.doSomething().doSomethingElse().getMyThing();
 </source>
 <p>is considered bad practice because it hides problems relating to
 synchronization, resource management, etc. The example above might
 become:</p>
 <source>
 final MySomething something = myObject.doSomething();
 final MyElse somethingElse = something.doSomethingElse();
 Thing thing = somethingElse.getMyThing();
 </source>
 <p>The extra typing will help keep the code bug-free.</p>

 <p>Thanks for your cooperation.</p>

 <p>-The Directory Project Team</p>

 </section>

 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<document>
	<properties>
	<author email="akarasulu@apache.org">Alex Karasulu</author>
	<title>Apache Directory Project: Coding Standards</title>
	</properties>
	<body>
	<section name="Coding Standards">
	<p>This document describes a list of coding conventions that are required
	for code submissions to the project. By default, the coding conventions
	for most Open Source projects should follow the existing coding conventions
	in the code that you are working on. For example, if the bracket is on
	the same line as the if statement, then you should write all your code
	to follow that convention.</p>

	<p><strong>Please follow these conventions closely. It makes life so much
	easier.</strong></p>

	<p>Brackets should begin and end on a new line. Examples:</p>
	<source>

	if( foo )
	{
	// code here
	}

	try
	{
	// code here
	}
	catch( final Exception bar )
	{
	// code here
	}
	finally
	{
	// code here
	}

	while( true )
	{
	// code here
	}

	</source>

	<p>The preference is to include extra spaces between parenthesis and expression.
	For example;
	</p>
	<source>

	if( foo )

	</source>
	<p>4 spaces. <strong>NO</strong> tabs. Period. We understand that a lot of you like
	to use tabs, but the fact of the matter is that in a distributed development
	environment, when the cvs commit messages get sent to a mailing list, they
	are almost impossible to read if you use tabs.</p>

	<p>In Emacs-speak, this translates to the following command:</p>

	<source>(setq-default tab-width 4 indent-tabs-mode nil)</source>

	<p>In vim, having the following in your .vimrc will help:</p>
	<source>
	set tabstop=4
	set expandtab
	set list
	set listchars=tab:>.
	</source>

	<p>Unix linefeeds for all .java source code files. Other platform specific
	files should have the platform specific linefeeds.</p>

	<p>Javadoc <strong>SHOULD</strong> exist on all your methods. Also, if you are working
	on existing code and there currently isn't a javadoc for that method/class/variable
	or whatever, then you should contribute and add it. This will improve the
	project as a whole.</p>

	<p>The Jakarta Apache/Directory License <strong>MUST</strong> be placed at the
	top of each and every file.</p>

	<p>If you contribute to a file (code or documentation), add the following author tag to the
	top of the file. For .java files the preferred Javadoc format is:</p>

	<source>
	@author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
	</source>

	<p>Indent comments on an 80 column basis and the code on a
	100 column basis, using two more indents when a line must be wrapped.</p>

	<p>We focus on readability over performance, at least initially. Source code
	optimization is the last thing to be done to increase performance.
	If the code is not performing then it is better to re-engineer it rather
	than to expand loops, take out variable declarations etc. When the code
	is stable and has a well defined purpose and interface it may be appropriate
	to do source code optimization.</p>

	<p>Try to javadoc all methods and variables, especially public, protected
	and default access methods and member variables. Also add code comments
	when you think it's necessary (like assumptions).</p>

	<p>Variables are declared in the inner scope.</p>

	<source>
	while( myListIterator.hasNext() )
	{
	final String myString = (String)myListIterator.next();
	}
	</source>

	<p>Variables should be descriptive and ideally English words. The exceptions
	being loop counters (usually use i, j and k), exceptions (use concatenation
	of word separating characters - i.e. SocketException is abbreviated as se) and
	other commonly used abbreviations (i.e. sb for StringBuffer).</p>
	<source>
	try
	{
	for( int i = 0; i < 10; i++ )
	{
	// some stuff
	}
	}
	catch( final FileNotFoundException fnfe )
	{
	// some stuff
	}
	catch( final IndexOutOfBoundsException ioobe )
	{
	// some stuff
	}
	</source>
	<p>
	Use String concatenation except in extremely performance sensitive
	sections. This leaves StringBuffer optimization to the compiler.
	So use:</p>
	<source>
	final String myString = "test " + "for " + "performances";
	</source>
	<p>Try not to declare a method as 'synchronized'. If a method accesses
	a shared resource then surround accesses to that resource with
	a synchronized block. Ideally the synchronized block should surround
	the smallest possible area. For example:</p>
	<source>
	public void sharedMethod()
	{
	String display = null;

	synchronized( this )
	{
	display = mySharedObject.getHelloWorld();
	}

	System.out.println( display );
	}
	</source>
	<p>If you are within a static method, then you may have to create
	a static object whose sole purpose in life is to provide the
	lock you need. Alternatively you could use the Class object for
	the class you are in. That is, if you're in class MyClass, use
	"MyClass.class".</p>
	<p>Have the names of all member instance fields start with the prefix "m_".
	Example:</p>

	<source>
	class MyClass
	{
	Class m_class = MyClass.class;
	int m_users;
	}
	</source>

	<p>Don't chain method calls. The below:</p>
	<source>
	Thing thing = (MyThing)myObject.doSomething().doSomethingElse().getMyThing();
	</source>
	<p>is considered bad practice because it hides problems relating to
	synchronization, resource management, etc. The example above might
	become:</p>
	<source>
	final MySomething something = myObject.doSomething();
	final MyElse somethingElse = something.doSomethingElse();
	Thing thing = somethingElse.getMyThing();
	</source>
	<p>The extra typing will help keep the code bug-free.</p>

	<p>Thanks for your cooperation.</p>

	<p>-The Directory Project Team</p>

	</section>

	</body>
	</document>