Skip to main content
Jump to: navigation, search

Difference between revisions of "MoDisco/CodingConventions"

(Checkstyle Usage)
(Java Code Formatting)
 
(9 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
=== Eclipse JDT Warnings Level<br> ===
 
=== Eclipse JDT Warnings Level<br> ===
  
For code style verification, it is recommended to configure Eclipse jdt settings for errors/warning levels : all rules levels set as "ignored" should be set as "warning".<br>
+
For code style verification, it is recommended to configure Eclipse JDT settings for errors/warning levels : all rules levels set as "ignored" should be set as "warning".<br>
  
Some rules might create too many constraints in some java circumstances. The developer is allowed to disactivate the rules in specific areas :<br>
+
Some rules might create too many constraints on Java code in some circumstances. The developer is allowed to deactivate the rules in specific areas :<br>
  
 
- with projects specific errors/warning levels.<br>
 
- with projects specific errors/warning levels.<br>
  
- with @SuppressWarnings, in adding some explanation to the deviation.<br>
+
- with @SuppressWarnings, adding some explanation to justify the deviation.<br>
 +
 
 +
 
 +
'''''Eclipse JDT Levels for EMF generated classes'''''
 +
 
 +
For instance, here are the typical project settings to "ignore" level for a Java EMF generated project :
 +
- Unqualified Access to instance field
 +
- Undocumented empty block
 +
- Parameter assignment
 +
- Boxing and unboxing conversions
 +
- Field declaration hides another field
 +
- Parameter is never read
 +
- Unused import
 +
- Unnecessary 'else'
 +
- Unnecessary cast or 'instanceof' operation
  
 
=== Checkstyle Usage  ===
 
=== Checkstyle Usage  ===
  
 
For MoDisco internal developments, the ''org.eclipse.gmt.modisco.dev.core'' project defines a MoDisco.checkstyle file.
 
For MoDisco internal developments, the ''org.eclipse.gmt.modisco.dev.core'' project defines a MoDisco.checkstyle file.
This file defines coding rules. It was initiated from the "sun conventions for Eclipse" checkstyle file. Some constraining rules have been disabled.
+
This file defines coding rules. It was initiated from the "Sun Checks (Eclipse)" default configuration. Some rules which were deemed too restrictive have been disabled.
  
 
This project is available in SVN: https://dev.eclipse.org/svnroot/modeling/org.eclipse.gmt.modisco/plugins/trunk/org.eclipse.gmt.modisco.dev.core/checkstyle/MoDisco.checkstyle
 
This project is available in SVN: https://dev.eclipse.org/svnroot/modeling/org.eclipse.gmt.modisco/plugins/trunk/org.eclipse.gmt.modisco.dev.core/checkstyle/MoDisco.checkstyle
  
 
For configuring a new IDE :
 
For configuring a new IDE :
* Install [http://eclipse-cs.sourceforge.net/ Checkstyle plug-in]
+
* Install the [http://eclipse-cs.sourceforge.net/ Checkstyle plug-in] (<code>http://eclipse-cs.sf.net/update/</code>)
 +
** version 5.1.0
  
* Go in ''Window > Preferences > Checkstyle'', and define a new global configuration of type 'Project Relative Configuration', pointing to the MoDisco.checkstyle file
+
*Each new MoDisco source project should have checkstyle enabled (context menu on the project, '''Checkstyle > Activate Checkstyle'''). Additional warnings are then computed on source code. A new builder is associated to the project.
  
Then each new MoDisco source project should have this checkstyle file applied (popup menu, ''Checkstyle > Activate Checkstyle''). Additional warnings are then computed on source code. A new builder is associated to the project.
+
*The <code>local-check-config</code> tag must be manually added to the .checkstyle file (see below) so that it points to the main checkstyle configuration file in <code>org.eclipse.gmt.modisco.dev.core</code>.
  
.checkstyle files are not required (except for local configuration explained below). Beware of not committing a useless .checkstyle because it references a specific checkstyle configuration name.
+
Here is an example checkstyle configuration file (.checkstyle). It ignores warnings on "Messages.java":
 
+
Some generated files (such as EMF generated files) do not comply with these rules. For such files, the warnings should be ignored, or the checkstyle may be deactivated for the whole EMF generated project.
+
 
+
==== Local configuration ====
+
It is also possible to configure checkstyle on a project, thus removing the need to configure it at the workspace level.
+
 
+
Here is an example checkstyle configuration file (.checkstyle). It references the checkstyle configuration file in the "modisco.dev.core" project and ignores warnings on "Messages.java":
+
  
 
   <?xml version="1.0" encoding="UTF-8"?>
 
   <?xml version="1.0" encoding="UTF-8"?>
Line 42: Line 50:
 
     </fileset>
 
     </fileset>
 
   </fileset-config>
 
   </fileset-config>
 +
 +
* Some generated files (such as EMF generated files) do not comply with the rules. For such files, the warnings can be ignored by selecting the package in section "Exclude from checking" in the checkstyle properties on the project, or checkstyle may be deactivated for the whole EMF generated project.
  
 
Reference:
 
Reference:
 
http://robertmarkbramprogrammer.blogspot.com/2007/07/eclipse-checkstyle-for-new-project.html
 
http://robertmarkbramprogrammer.blogspot.com/2007/07/eclipse-checkstyle-for-new-project.html
  
==== Checkstyle is not an Eclipse.org tool ====
+
==== IP status ====
  
 
Note that Checkstyle is not an Eclipse.org tool. However, its source code is under the EPL, and its current use has been formally IP-validated for the MoDisco project:  
 
Note that Checkstyle is not an Eclipse.org tool. However, its source code is under the EPL, and its current use has been formally IP-validated for the MoDisco project:  
Line 54: Line 64:
  
 
Also note that Checkstyle is not intended to be distributed with MoDisco.
 
Also note that Checkstyle is not intended to be distributed with MoDisco.
 +
 +
=== Java Code Formatting ===
 +
 +
Each Contributor/Commiter is free to define its column number limit per line (global Java Editor setting in Eclipse IDE Preferences).
 +
 +
However in order to avoid some annoying version control differences, it is asked to '''not activate formatting save action''' (global Java Editor setting in Eclipse IDE Preferences) and only apply locally Eclipse formatter to the Java lines modified/added.
 +
It is asked to '''not define formatting settings locally to one java project''', in order to let the developer work with its own formatting preferences.

Latest revision as of 03:24, 19 April 2011


Eclipse JDT Warnings Level

For code style verification, it is recommended to configure Eclipse JDT settings for errors/warning levels : all rules levels set as "ignored" should be set as "warning".

Some rules might create too many constraints on Java code in some circumstances. The developer is allowed to deactivate the rules in specific areas :

- with projects specific errors/warning levels.

- with @SuppressWarnings, adding some explanation to justify the deviation.


Eclipse JDT Levels for EMF generated classes

For instance, here are the typical project settings to "ignore" level for a Java EMF generated project : - Unqualified Access to instance field - Undocumented empty block - Parameter assignment - Boxing and unboxing conversions - Field declaration hides another field - Parameter is never read - Unused import - Unnecessary 'else' - Unnecessary cast or 'instanceof' operation

Checkstyle Usage

For MoDisco internal developments, the org.eclipse.gmt.modisco.dev.core project defines a MoDisco.checkstyle file. This file defines coding rules. It was initiated from the "Sun Checks (Eclipse)" default configuration. Some rules which were deemed too restrictive have been disabled.

This project is available in SVN: https://dev.eclipse.org/svnroot/modeling/org.eclipse.gmt.modisco/plugins/trunk/org.eclipse.gmt.modisco.dev.core/checkstyle/MoDisco.checkstyle

For configuring a new IDE :

  • Each new MoDisco source project should have checkstyle enabled (context menu on the project, Checkstyle > Activate Checkstyle). Additional warnings are then computed on source code. A new builder is associated to the project.
  • The local-check-config tag must be manually added to the .checkstyle file (see below) so that it points to the main checkstyle configuration file in org.eclipse.gmt.modisco.dev.core.

Here is an example checkstyle configuration file (.checkstyle). It ignores warnings on "Messages.java":

 <?xml version="1.0" encoding="UTF-8"?>
 <fileset-config file-format-version="1.2.0" simple-config="true">
   <local-check-config name="MoDisco" location="../org.eclipse.gmt.modisco.dev.core/checkstyle/MoDisco.checkstyle" type="project" description=""/>
   <fileset name="all" enabled="true" check-config-name="MoDisco" local="true">
     <file-match-pattern match-pattern="." include-pattern="true"/>
     <file-match-pattern match-pattern="Messages.java" include-pattern="false"/>
   </fileset>
 </fileset-config>
  • Some generated files (such as EMF generated files) do not comply with the rules. For such files, the warnings can be ignored by selecting the package in section "Exclude from checking" in the checkstyle properties on the project, or checkstyle may be deactivated for the whole EMF generated project.

Reference: http://robertmarkbramprogrammer.blogspot.com/2007/07/eclipse-checkstyle-for-new-project.html

IP status

Note that Checkstyle is not an Eclipse.org tool. However, its source code is under the EPL, and its current use has been formally IP-validated for the MoDisco project:

Also note that Checkstyle is not intended to be distributed with MoDisco.

Java Code Formatting

Each Contributor/Commiter is free to define its column number limit per line (global Java Editor setting in Eclipse IDE Preferences).

However in order to avoid some annoying version control differences, it is asked to not activate formatting save action (global Java Editor setting in Eclipse IDE Preferences) and only apply locally Eclipse formatter to the Java lines modified/added. It is asked to not define formatting settings locally to one java project, in order to let the developer work with its own formatting preferences.

Back to the top