Jump to: navigation, search

Difference between revisions of "PTP/policy/developer guidelines"

< PTP‎ | policy
(Java Errors/Warnings)
Line 1: Line 1:
 
PTP adheres to the [http://wiki.eclipse.org/Development_Conventions_and_Guidelines Eclipse Foundation development conventions and guidelines]. Please make sure you read through these before committing code (if you're a committer) or submitting code contributions (if not).  
 
PTP adheres to the [http://wiki.eclipse.org/Development_Conventions_and_Guidelines Eclipse Foundation development conventions and guidelines]. Please make sure you read through these before committing code (if you're a committer) or submitting code contributions (if not).  
  
The following practices should also be observed:
+
The following practices should also be observed:  
  
* All source files must start with an [http://www.eclipse.org/legal/copyrightandlicensenotice.php approved license and copyright declaration]
+
*All source files must start with an [http://www.eclipse.org/legal/copyrightandlicensenotice.php approved license and copyright declaration]  
* All plugins must include an [http://www.eclipse.org/legal/epl/about.php about.html file]
+
*All plugins must include an [http://www.eclipse.org/legal/epl/about.php about.html file]
  
== Java Errors/Warnings ==
+
== Java Errors/Warnings ==
  
Developers should override default compiler error/warning and use project specific errors/warnings. These errors should be enabled:
+
Developers should override default compiler error/warning and use project specific errors/warnings. These errors should be enabled:  
  
* Method with a constructor name - Error
+
*Method with a constructor name - Error  
* Non-externalized strings (missing/unused $NON-NLS$ tag) - Warning
+
*Non-externalized strings (missing/unused $NON-NLS$ tag) - Warning  
* Assignment has no effect - Error
+
*Assignment has no effect - Error  
* Possible accidental boolean assignment - Error
+
*Possible accidental boolean assignment - Error  
* finally does not complete normally - Error
+
*finally does not complete normally - Error  
* Using a char array in string concatenation - Error
+
*Using a char array in string concatenation - Error  
* Null pointer access - Error
+
*Null pointer access - Error  
* Potential null pointer access - Warning
+
*Potential null pointer access - Warning  
* Unused Import - Error
+
*Unused Import - Error
  
All committers and contributors submitting patches should enable [[PDE/API_Tools/User_Guide#API_Tooling_Setup|API tooling]] by setting target baseline platform. Do not commit code with API errors.
+
All committers and contributors submitting patches should enable [[PDE/API Tools/User Guide#API_Tooling_Setup|API tooling]] by setting target baseline platform. Do not commit code with API errors.  
  
<b>Patches with errors listed above including API errors will not be accepted without corrections.</b>
+
'''Patches with errors listed above including API errors will not be accepted without corrections.'''
  
== Additional requirements for Java source ==
+
== Additional requirements for Java source ==
  
* Use interfaces as much as possible
+
*Use interfaces as much as possible  
* All interfaces and methods must include a Javadoc comment
+
*All interfaces and methods must include a Javadoc comment  
* Interface implementations must include a non-Javadoc comment (using Generate Element Comment)
+
*Interface implementations must include a non-Javadoc comment (using Generate Element Comment)  
* All classes, methods and fields should have an access modifier (public, protected, private)
+
*All classes, methods and fields should have an access modifier (public, protected, private)  
* Use the following class, method and field modifier order:
+
*Use the following class, method and field modifier order:  
*# Access modifier
+
*#Access modifier  
*# abstract
+
*#abstract  
*# static
+
*#static  
*# final
+
*#final  
*# transient
+
*#transient  
*# volatile
+
*#volatile  
* All source should be formatted using the "Eclipse" built-in code formatter
+
*All source should be formatted using the "PTP" code formatter profile
* All members should be sorted
+
*All members should be cleaned up using the "PTP" profile (Source-&gt;Clean Up)
  
== Additional requirements for C source ==
+
The PTP formatter and clean-up profiles are available [http://wiki.eclipse.org/images/a/a9/Ptp_format.zip here].
  
* All functions must be commented
+
== Additional requirements for C source  ==
* Only include header files that are explicitly used
+
* Always initialize variables before use (including static)
+
* Always test explicitly for NULL
+
* Always use NULL for pointers, not 0
+
* Always test for an explicit value from strcmp
+
  
C source formatting guidelines:
+
*All functions must be commented
 +
*Only include header files that are explicitly used
 +
*Always initialize variables before use (including static)
 +
*Always test explicitly for NULL
 +
*Always use NULL for pointers, not 0
 +
*Always test for an explicit value from strcmp
  
* Function body '{' and '}' on their own line
+
C source formatting guidelines:
* Function type on its own line (including static qualifier)
+
* Function arguments separated by one space
+
* Functions local to a file should be declared static
+
* One variable declaration per line
+
* Variable declarations should be followed by a blank line
+
* No spaces before or after '(' and ')' in functions
+
* Opening brace on same line as last ')' in an if statement expression
+
* Space separating 'if' and '('
+
* No spaces after '(' or before ')' in if statements
+
* No braces around return values
+
* Opening brace on same line as 'else'
+
* 'else' on same line as '}'
+
* Only use '/*' and '*/' for comments
+
* Put '/*' and '*/' on their own line for multiline comments
+
* Start each line of a multiline comment with an '*' aligned with the '*' in the '/*'
+
  
Naming conventions for global objects:
+
*Function body '{' and '}' on their own line
 +
*Function type on its own line (including static qualifier)
 +
*Function arguments separated by one space
 +
*Functions local to a file should be declared static
 +
*One variable declaration per line
 +
*Variable declarations should be followed by a blank line
 +
*No spaces before or after '(' and ')' in functions
 +
*Opening brace on same line as last ')' in an if statement expression
 +
*Space separating 'if' and '('
 +
*No spaces after '(' or before ')' in if statements
 +
*No braces around return values
 +
*Opening brace on same line as 'else'
 +
*'else' on same line as '}'
 +
*Only use '/*' and '*/' for comments
 +
*Put '/*' and '*/' on their own line for multiline comments
 +
*Start each line of a multiline comment with an '*' aligned with the '*' in the '/*'
  
* Capitalize the first letter of each word (e.g.MIBreakpointGetBreakInsertInfo)
+
Naming conventions for global objects:
* Do not use '_' or '-'
+
* Use descriptive names
+
  
Naming conventions for local/utility objects:
+
*Capitalize the first letter of each word (e.g.MIBreakpointGetBreakInsertInfo)
 +
*Do not use '_' or '-'
 +
*Use descriptive names
  
* All lowercase
+
Naming conventions for local/utility objects:
* Separate words with '_'
+
 
* Do not use '-'
+
*All lowercase  
 +
*Separate words with '_'  
 +
*Do not use '-'

Revision as of 16:32, 29 July 2010

PTP adheres to the Eclipse Foundation development conventions and guidelines. Please make sure you read through these before committing code (if you're a committer) or submitting code contributions (if not).

The following practices should also be observed:

Java Errors/Warnings

Developers should override default compiler error/warning and use project specific errors/warnings. These errors should be enabled:

  • Method with a constructor name - Error
  • Non-externalized strings (missing/unused $NON-NLS$ tag) - Warning
  • Assignment has no effect - Error
  • Possible accidental boolean assignment - Error
  • finally does not complete normally - Error
  • Using a char array in string concatenation - Error
  • Null pointer access - Error
  • Potential null pointer access - Warning
  • Unused Import - Error

All committers and contributors submitting patches should enable API tooling by setting target baseline platform. Do not commit code with API errors.

Patches with errors listed above including API errors will not be accepted without corrections.

Additional requirements for Java source

  • Use interfaces as much as possible
  • All interfaces and methods must include a Javadoc comment
  • Interface implementations must include a non-Javadoc comment (using Generate Element Comment)
  • All classes, methods and fields should have an access modifier (public, protected, private)
  • Use the following class, method and field modifier order:
    1. Access modifier
    2. abstract
    3. static
    4. final
    5. transient
    6. volatile
  • All source should be formatted using the "PTP" code formatter profile
  • All members should be cleaned up using the "PTP" profile (Source->Clean Up)

The PTP formatter and clean-up profiles are available here.

Additional requirements for C source

  • All functions must be commented
  • Only include header files that are explicitly used
  • Always initialize variables before use (including static)
  • Always test explicitly for NULL
  • Always use NULL for pointers, not 0
  • Always test for an explicit value from strcmp

C source formatting guidelines:

  • Function body '{' and '}' on their own line
  • Function type on its own line (including static qualifier)
  • Function arguments separated by one space
  • Functions local to a file should be declared static
  • One variable declaration per line
  • Variable declarations should be followed by a blank line
  • No spaces before or after '(' and ')' in functions
  • Opening brace on same line as last ')' in an if statement expression
  • Space separating 'if' and '('
  • No spaces after '(' or before ')' in if statements
  • No braces around return values
  • Opening brace on same line as 'else'
  • 'else' on same line as '}'
  • Only use '/*' and '*/' for comments
  • Put '/*' and '*/' on their own line for multiline comments
  • Start each line of a multiline comment with an '*' aligned with the '*' in the '/*'

Naming conventions for global objects:

  • Capitalize the first letter of each word (e.g.MIBreakpointGetBreakInsertInfo)
  • Do not use '_' or '-'
  • Use descriptive names

Naming conventions for local/utility objects:

  • All lowercase
  • Separate words with '_'
  • Do not use '-'