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

From Eclipsepedia

< PTP‎ | policy
Jump to: navigation, search
(Additional requirements for C source)
(PTP formatting and cleanup profiles for Java)
(27 intermediate revisions by 5 users not shown)
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 follows the standard requirements for working on Eclipse projects Please ensure you have read the [[Development Resources | Eclipse Development Resources]] prior to beginning work.
 +
 
 +
PTP also adheres to the [[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:  
Line 5: Line 7:
 
*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]
 +
 +
== Contributions from non-committers ==
 +
 +
Contributions from non-committers should be handled by following these guidelines: [[Development Resources/Handling Git Contributions|Handling Git Contributions]]
  
 
== Java Errors/Warnings  ==
 
== Java Errors/Warnings  ==
Line 20: Line 26:
 
*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.  
 +
See below for how to set up.
 +
Do not commit code with API errors.  
  
'''Patches with errors listed above including API errors will not be accepted without corrections.'''  
+
'''Patches with errors listed above including API errors will not be accepted without corrections.'''
 +
 
 +
== API Baseline setup  (API Tools) ==
 +
To enable API tooling / API Tools:
 +
 
 +
# Download the master archive of the previous major release of PTP.  This will be a file named ptp-master-xxx.zip.
 +
## Prior to June, 2012, this is [http://archive.eclipse.org/tools/ptp/builds/5.0.0/I.I201106140904/ptp-master-5.0.0-I201106140904.zip ptp-master-5.0.0-I201106140904.zip].
 +
## After June, 2012, this is [http://download.eclipse.org/tools/ptp/builds/juno/milestones/RC4/ptp-master-6.0.0-201206130212.zip ptp-master-6.0.0-201206130212.zip].
 +
# Unzip it into some directory (e.g. ptp-baseline-5.0.0 or ptp-baseline-6.0.0)
 +
# In Eclipse, go to Window>Preferences>Plug-in Development>API Baselines
 +
# Click Add Baselines...
 +
# Name your new baseline
 +
# Choose the directory from step 2 and click OK
 +
# Make sure the new baseline is the selected one
 +
# It will want to do a full build, which is what you want.
  
 
== Additional requirements for Java source  ==
 
== Additional requirements for Java source  ==
Line 37: Line 59:
 
*#transient  
 
*#transient  
 
*#volatile  
 
*#volatile  
*All source should be formatted using the "PTP" code formatter profile  
+
*All source should be formatted using the "PTP" code formatter profile (see below)
 
*All members should be cleaned up using the "PTP" profile (Source-&gt;Clean Up)
 
*All members should be cleaned up using the "PTP" profile (Source-&gt;Clean Up)
 +
*Statement blocks should always be used, even for single line 'if', 'for', etc.
 
*Column width should be set to 132
 
*Column width should be set to 132
 +
 +
=== PTP formatting and cleanup profiles for Java ===
  
 
The PTP formatter and clean-up profiles are available [http://wiki.eclipse.org/images/a/a9/Ptp_format.zip here].
 
The PTP formatter and clean-up profiles are available [http://wiki.eclipse.org/images/a/a9/Ptp_format.zip here].
 +
To use the profiles,
 +
* Unzip on your machine to find two files: ptp_format.xml and ptp_cleanup.xml
 +
* '''Formatter:''' in Window > Preferences > Java > Code Style > Formatter, Import...  and select the ptp_format.xml file. You should then see "PTP" as the active profile.
 +
** To use: Select a source file in Package Explorer (or container/folder/etc.) and select Source menu > Format
 +
* '''Cleanup''' in Window > Preferences > Java > Code Style > Clean Up, Import... and select the ptp_cleanup.xml file.  You should then see "PTP" as the active profile.
 +
** To use: Select a source file in Package Explorer (or container/folder/etc.) and select Source menu > Cleanup ...
 +
* Optionally '''Set the editor to apply the formatting changes automatically on save''' for convenience and consistency in use in Window > Preferences > Java > Editor > Save Actions. Check "Perform the selected actions on save", check "Format source code", and check "Additional actions"
  
 
== Adding new Plugin ==
 
== Adding new Plugin ==
  
 +
* Enable API Tooling on the plugin (PDE Tools>API Tools Setup..)
 
* Add the plugin to the anonymous and committer project sets for HEAD.
 
* Add the plugin to the anonymous and committer project sets for HEAD.
 
* Add the plugin to a feature so it gets built (in this case it should be org.eclipse.ptp.core-feature)
 
* Add the plugin to a feature so it gets built (in this case it should be org.eclipse.ptp.core-feature)
Line 62: Line 95:
 
*Always use NULL for pointers, not 0  
 
*Always use NULL for pointers, not 0  
 
*Always test for an explicit value from strcmp
 
*Always test for an explicit value from strcmp
 +
*All functions should be declared static unless explicitly exported with an 'extern' prototype in the header file
 +
*Filenames should be all lowercase with words separated by '_'
  
 
C source formatting guidelines:  
 
C source formatting guidelines:  
Line 72: Line 107:
 
*Variable declarations should be followed by a blank line  
 
*Variable declarations should be followed by a blank line  
 
*No spaces before or after '(' and ')' in functions  
 
*No spaces before or after '(' and ')' in functions  
*Opening brace on same line as last ')' in an if statement expression  
+
*Opening brace on same line as last ')' in an 'if', 'for', or 'switch' statement expression  
*Space separating 'if' and '('  
+
*Space separating keyword and '('  
 
*No spaces after '(' or before ')' in if statements  
 
*No spaces after '(' or before ')' in if statements  
 
*No braces around return values  
 
*No braces around return values  
Line 82: Line 117:
 
*Start each line of a multiline comment with an '*' aligned with the '*' in the '/*'
 
*Start each line of a multiline comment with an '*' aligned with the '*' in the '/*'
  
Naming conventions:
+
C naming conventions:
  
 
*Global function and type identifiers:  
 
*Global function and type identifiers:  

Revision as of 15:25, 31 May 2013

PTP follows the standard requirements for working on Eclipse projects Please ensure you have read the Eclipse Development Resources prior to beginning work.

PTP also adheres to the 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:

Contents

Contributions from non-committers

Contributions from non-committers should be handled by following these guidelines: Handling Git Contributions

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. See below for how to set up. Do not commit code with API errors.

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

API Baseline setup (API Tools)

To enable API tooling / API Tools:

  1. Download the master archive of the previous major release of PTP. This will be a file named ptp-master-xxx.zip.
    1. Prior to June, 2012, this is ptp-master-5.0.0-I201106140904.zip.
    2. After June, 2012, this is ptp-master-6.0.0-201206130212.zip.
  2. Unzip it into some directory (e.g. ptp-baseline-5.0.0 or ptp-baseline-6.0.0)
  3. In Eclipse, go to Window>Preferences>Plug-in Development>API Baselines
  4. Click Add Baselines...
  5. Name your new baseline
  6. Choose the directory from step 2 and click OK
  7. Make sure the new baseline is the selected one
  8. It will want to do a full build, which is what you want.

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 (see below)
  • All members should be cleaned up using the "PTP" profile (Source->Clean Up)
  • Statement blocks should always be used, even for single line 'if', 'for', etc.
  • Column width should be set to 132

PTP formatting and cleanup profiles for Java

The PTP formatter and clean-up profiles are available here. To use the profiles,

  • Unzip on your machine to find two files: ptp_format.xml and ptp_cleanup.xml
  • Formatter: in Window > Preferences > Java > Code Style > Formatter, Import... and select the ptp_format.xml file. You should then see "PTP" as the active profile.
    • To use: Select a source file in Package Explorer (or container/folder/etc.) and select Source menu > Format
  • Cleanup in Window > Preferences > Java > Code Style > Clean Up, Import... and select the ptp_cleanup.xml file. You should then see "PTP" as the active profile.
    • To use: Select a source file in Package Explorer (or container/folder/etc.) and select Source menu > Cleanup ...
  • Optionally Set the editor to apply the formatting changes automatically on save for convenience and consistency in use in Window > Preferences > Java > Editor > Save Actions. Check "Perform the selected actions on save", check "Format source code", and check "Additional actions"

Adding new Plugin

  • Enable API Tooling on the plugin (PDE Tools>API Tools Setup..)
  • Add the plugin to the anonymous and committer project sets for HEAD.
  • Add the plugin to a feature so it gets built (in this case it should be org.eclipse.ptp.core-feature)
  • Add the plugin to the map file org.eclipse.releng/maps/ptp.map
  • Add a tagone entry in the tag target in org.eclipse.ptp.releng/build.xml
  • Add a about.html
  • Announce on ptp-dev

There is some documentation on the release engineering here: http://wiki.eclipse.org/PTP/release_engineering

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
  • All functions should be declared static unless explicitly exported with an 'extern' prototype in the header file
  • Filenames should be all lowercase with words separated by '_'

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', 'for', or 'switch' statement expression
  • Space separating keyword 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 '/*'

C naming conventions:

  • Global function and type identifiers:
    • Capitalize the first letter of each word (e.g.MIBreakpointGetBreakInsertInfo)
    • Do not use '_' or '-'
    • Use descriptive names
  • Local (static) and utility function and type identifiers, and structure field identifiers:
    • All lowercase
    • Separate words with '_'
    • Do not use '-'
  • Local (static) variables:
    • Can start with '_'