Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Papyrus/Code Standards"

(Java classes)
(Coding rules for Papyrus plug-ins and features)
(2 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
These rules apply to all plug-ins and features developed for the Papyrus Eclipse project, and distributed under the EPL licence.  
 
These rules apply to all plug-ins and features developed for the Papyrus Eclipse project, and distributed under the EPL licence.  
 +
  
 
== Plug-ins ==
 
== Plug-ins ==
Line 12: Line 13:
 
**Luna : ''1.0.0.qualifier'' or ''0.11.0.qualifier''
 
**Luna : ''1.0.0.qualifier'' or ''0.11.0.qualifier''
 
**Mars : ''1.1.0.qualifier'' or ''0.12.0.qualifier''
 
**Mars : ''1.1.0.qualifier'' or ''0.12.0.qualifier''
**Neon : ''1.2.0.qualifier''
+
**Neon : ''as of this release, Papyrus adheres to the [[Version Numbering|Eclipse Versioning Guidelines]] for API evolution and other kinds of changes''
 
*Plug-in name : must end with (Incubation) if version is less than 1.0. e.g. ''Papyrus CDO Model Repository (Incubation)''. If the version is at least 1.0.0, the (Incubation) suffix must be removed (e.g. ''Papyrus Backbone'').
 
*Plug-in name : must end with (Incubation) if version is less than 1.0. e.g. ''Papyrus CDO Model Repository (Incubation)''. If the version is at least 1.0.0, the (Incubation) suffix must be removed (e.g. ''Papyrus Backbone'').
 
*Plug-in ID : must start with org.eclipse.papyrus  
 
*Plug-in ID : must start with org.eclipse.papyrus  
*Plug-in dependencies must not be re-exported  
+
*Plug-in dependencies must be re-exported that contribute types to the API signatures exported by the plug-in.  This ensures a correct and consistent classpath for consuming bundles
*Dependencies to Papyrus plug-ins must match the current version (e.g. depend on ''oep.infra.core 1.0.0'' instead of ''oep.infra.core'')  
+
**The Papyrus Developer Tools include an action '''Optimize Bundle Dependencies''' in the '''Plug-in Tools''' context menu of plug-in projects and manifest files that automatically re-exports the minimal set of dependencies to cover all imported APIs that are exposed by a plug-in
 +
*Dependencies to Papyrus plug-ins must match the current compatible version (e.g. depend on ''oep.infra.core;bundle-version="[1.2.0,2.0.0)"'' instead of ''oep.infra.core'' or ''oep.infra.core;bundle-version="1.2.0"'')
 +
**The Papyrus Developer Tools include an action '''Update Dependency Ranges''' in the '''Plug-in Tools''' context menu of plug-in projects and manifest files that automatically assigns bundle dependency ranges compatible with the current PDE target and workspace
 
*The build.properties file describes the files that '''must''' be included at runtime. It is important to fill it properly, so that plug-ins can work correctly once installed. Especially, you should probably always include the following files and folders (When they exist), in the "Binary build" category:  
 
*The build.properties file describes the files that '''must''' be included at runtime. It is important to fill it properly, so that plug-ins can work correctly once installed. Especially, you should probably always include the following files and folders (When they exist), in the "Binary build" category:  
 
**META-INF/  
 
**META-INF/  
Line 40: Line 43:
 
plugin.xml:<br>
 
plugin.xml:<br>
 
[[Image:Papyrus.codestandards.plugin.xml.png]]
 
[[Image:Papyrus.codestandards.plugin.xml.png]]
 +
  
 
== Java classes ==
 
== Java classes ==
  
 
*All APIs must be documented with JavaDoc comments. Automatic generation of JavaDoc comments may help, but the automatically generated comments are '''templates'''. They are not sufficient. It is better not to generate javadoc comments than to generate empty comments.  
 
*All APIs must be documented with JavaDoc comments. Automatic generation of JavaDoc comments may help, but the automatically generated comments are '''templates'''. They are not sufficient. It is better not to generate javadoc comments than to generate empty comments.  
 +
*No abbreviations - the class, methods and variables should have meaningful names
 +
*Formatting - the code should be formatted in accordance with format templates
 +
*Always use brackets in conditions, loops, ...
 +
*Compile - the modified code and other plugins should be compilable. Be sure to use '''Java 1.5 code compatibility'''. Check other plugins that could be influenced before commiting!
 +
*Standard Java Rules coding - Unless specified differently, the Java Standard Coding rules should be applied: no abbreviations, variables starting with lower case; class and types with upper case; Composed name separated with upper case; no underscore in names; ...
 +
 
*Each Java class must contain the Copyright/Licence/Contributor header. e.g.:
 
*Each Java class must contain the Copyright/Licence/Contributor header. e.g.:
  
Line 59: Line 69:
  
 
*You must '''not''' use the standard console output in Papyrus plug-ins. Use the [[Papyrus Developer Guide/Papyrus Log|Papyrus log]] instead
 
*You must '''not''' use the standard console output in Papyrus plug-ins. Use the [[Papyrus Developer Guide/Papyrus Log|Papyrus log]] instead
 +
 +
*In case of doubt - check existing code from those following the rules&nbsp;:-)
 +
  
 
== Features  ==
 
== Features  ==

Revision as of 12:39, 25 January 2018

Coding rules for Papyrus plug-ins and features

These rules apply to all plug-ins and features developed for the Papyrus Eclipse project, and distributed under the EPL licence.


Plug-ins

  • All plug-ins must compile and run with Java 1.7 (Execution Environment = JavaSE-1.7). Starting with Papyrus 1.2.0 / Neon, JavaSE-1.8 is also allowed
  • Plug-in provider : Eclipse Modeling Project
  • Version :
    • Juno : 0.9.2.qualifier
    • Kepler : 0.10.0.qualifier
    • Luna : 1.0.0.qualifier or 0.11.0.qualifier
    • Mars : 1.1.0.qualifier or 0.12.0.qualifier
    • Neon : as of this release, Papyrus adheres to the Eclipse Versioning Guidelines for API evolution and other kinds of changes
  • Plug-in name : must end with (Incubation) if version is less than 1.0. e.g. Papyrus CDO Model Repository (Incubation). If the version is at least 1.0.0, the (Incubation) suffix must be removed (e.g. Papyrus Backbone).
  • Plug-in ID : must start with org.eclipse.papyrus
  • Plug-in dependencies must be re-exported that contribute types to the API signatures exported by the plug-in. This ensures a correct and consistent classpath for consuming bundles
    • The Papyrus Developer Tools include an action Optimize Bundle Dependencies in the Plug-in Tools context menu of plug-in projects and manifest files that automatically re-exports the minimal set of dependencies to cover all imported APIs that are exposed by a plug-in
  • Dependencies to Papyrus plug-ins must match the current compatible version (e.g. depend on oep.infra.core;bundle-version="[1.2.0,2.0.0)" instead of oep.infra.core or oep.infra.core;bundle-version="1.2.0")
    • The Papyrus Developer Tools include an action Update Dependency Ranges in the Plug-in Tools context menu of plug-in projects and manifest files that automatically assigns bundle dependency ranges compatible with the current PDE target and workspace
  • The build.properties file describes the files that must be included at runtime. It is important to fill it properly, so that plug-ins can work correctly once installed. Especially, you should probably always include the following files and folders (When they exist), in the "Binary build" category:
    • META-INF/
    • about.html
    • icons/, images/, resources/, models/, etc. (All folders containing runtime resources)
    • plugin.properties
    • plugin.xml
    • schema/
  • Do not include the following files:
    • .classpath
    • .project
    • bin/, src/, src-gen/, custom-src/
    • build.properties
  • The Source build category must contain the following file:
    • about.html
  • Optionnally, it may contain the following files:
    • .classpath
    • build.properties
  • It must not contain the following:
    • src/, src-gen/, custom-src/
    • All files and directories which are already contained in the "Binary build" category (Except about.html which must be contained in both Binary and Source builds)

plugin.xml:
Papyrus.codestandards.plugin.xml.png


Java classes

  • All APIs must be documented with JavaDoc comments. Automatic generation of JavaDoc comments may help, but the automatically generated comments are templates. They are not sufficient. It is better not to generate javadoc comments than to generate empty comments.
  • No abbreviations - the class, methods and variables should have meaningful names
  • Formatting - the code should be formatted in accordance with format templates
  • Always use brackets in conditions, loops, ...
  • Compile - the modified code and other plugins should be compilable. Be sure to use Java 1.5 code compatibility. Check other plugins that could be influenced before commiting!
  • Standard Java Rules coding - Unless specified differently, the Java Standard Coding rules should be applied: no abbreviations, variables starting with lower case; class and types with upper case; Composed name separated with upper case; no underscore in names; ...
  • Each Java class must contain the Copyright/Licence/Contributor header. e.g.:
/*****************************************************************************
 * Copyright (c) 2016 CEA LIST.
 * 
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *  Camille Letavernier (CEA LIST) camille.letavernier@cea.fr - Initial API and implementation
 *****************************************************************************/
  • You must not use the standard console output in Papyrus plug-ins. Use the Papyrus log instead
  • In case of doubt - check existing code from those following the rules :-)


Features

  • ID:
    • Main Papyrus components: org.eclipse.papyrus.<feature.name>.feature
      • e.g. org.eclipse.papyrus.infra.core.feature
    • Extra components: org.eclipse.papyrus.extra.<feature.name>.feature
      • e.g. org.eclipse.papyrus.extra.marte.feature
  • Name: Papyrus <Feature Name> (Incubation)
    • e.g. Papyrus core (Incubation)
    • e.g. Papyrus Marte (Incubation)
  • Each feature must contain the files epl-v10.html and license.html (April 9, 2014)
  • The build.properties file must contain the following files in the "Binary build" section:
    • epl-v10.html
    • feature.properties (When available)
    • feature.xml
    • licence.html
  • The build.properties file must contain the following files in the "Source build" section:
    • build.properties (Optional)
    • epl-v10.html
    • licence.html


Papyrus.Build.properties-selectedOptions.png

Tests

Test plug-ins

Each plug-in contributed within the Papyrus project must be accompanied with a Test plug-in (And their associated Feature). Each test plug-in must at least contain a test class so that it can be included to the build/test infrastructure. Of course, the more tests it actually contains, the better...

The test plug-ins and features must follow the same rules as the other Papyrus plug-ins.

Automatic check

Most of these rules are checked automatically when running the Papyrus tests. If you want to check them locally, use the plug-in org.eclipse.papyrus.bundles.tests (Run as > Junit plug-in test or use the *.launch file from this plug-in). This plug-in can be retrieved on the Papyrus Git repository: http://git.eclipse.org/c/papyrus/org.eclipse.papyrus.git/tree/tests/junit/plugins/developer/org.eclipse.papyrus.bundles.tests

Back to the top