Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "RAP/CodingStandards"
m |
(Remove rules for structured programming) |
||
Line 1: | Line 1: | ||
This document describes the coding conventions used by the RAP project. | This document describes the coding conventions used by the RAP project. | ||
− | '''Note''': These conventions affect only code created by the RAP project. | + | '''Note''': These conventions affect only code created by the RAP project. Code from SWT, JFace and RCP is not re-formatted. |
We follow the Oracle (Sun) conventions for the Java language: [http://www.oracle.com/technetwork/java/codeconvtoc-136057.html oracle.com/technetwork/java/codeconvtoc-136057.html] (Note that this includes braces around if, while and for constructs even if their 'then'-clause or body has only one line; see section 7.4 of the conventions.) Apart from that, the following rules are mandatory: | We follow the Oracle (Sun) conventions for the Java language: [http://www.oracle.com/technetwork/java/codeconvtoc-136057.html oracle.com/technetwork/java/codeconvtoc-136057.html] (Note that this includes braces around if, while and for constructs even if their 'then'-clause or body has only one line; see section 7.4 of the conventions.) Apart from that, the following rules are mandatory: | ||
Line 44: | Line 44: | ||
==== No parameter assignments ==== | ==== No parameter assignments ==== | ||
Method parameters must never be overwritten by an assignment. | Method parameters must never be overwritten by an assignment. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==== Initialize in constructor ==== | ==== Initialize in constructor ==== | ||
Line 107: | Line 67: | ||
==== No empty lines ==== | ==== No empty lines ==== | ||
− | Empty lines in methods are | + | Empty lines in methods are discouraged. The desire to separate code blocks with empty lines is often an indication that a methods does more than one thing. Consider to extract these blocks into methods of their own. |
− | An exception | + | An exception to this rule are unit tests. To visually emphasize the set up - execute - assert structure it is permitted to separate these with empty lines like in the example below: |
public void testFoo() { | public void testFoo() { |
Revision as of 10:36, 19 December 2013
This document describes the coding conventions used by the RAP project.
Note: These conventions affect only code created by the RAP project. Code from SWT, JFace and RCP is not re-formatted.
We follow the Oracle (Sun) conventions for the Java language: oracle.com/technetwork/java/codeconvtoc-136057.html (Note that this includes braces around if, while and for constructs even if their 'then'-clause or body has only one line; see section 7.4 of the conventions.) Apart from that, the following rules are mandatory:
Contents
General rules for text files
Unix newlines
Text files must use only Unix line delimiters (\n
).
UTF-8
If files contain non-ASCII characters, they have to be UTF-8 encoded.
No TABs
We use spaces only to indent. TAB characters are forbidden in RAP source files.
100 chars per line
We just decided to extend the line length from 80 to 100 characters. This is a hard limit.
Java code
Spaces inside braces
Insert a space after opening braces and before closing braces. Examples:
if( value == array[ i ] ) { someMethod( arg1, arg2 ); }
while( count <= maxNumber ) { ...
Linebreak before operators
If lines are broken at an operator, the operator must be on the next line, and the next line is indented once. There must be no naked operators at the end of a line. Example:
String message = "Long text that does not fit on a " + "single line...";
Speaking names
Use speaking names for variables, methods and classes. One letter names are only allowed as loop variables in loops.
No parameter assignments
Method parameters must never be overwritten by an assignment.
Initialize in constructor
Fields should be initialized in the constructor, not in the declaration statement.
One thing per line
In general, do one thing in one line. For example, don't write
int count = 0, line = 1; // BAD
but instead:
int count = 0; int line = 1;
No misused for
loops
Use for
loops only if there is a known number of iterations in the loop, otherwise use while
loops.
Particularly, don't use for
loops to iterate over a list iterator.
@since
Tags
All public API must be marked with a @since
tag at the class/interface level. Only methods, fields etc. that are added in a later release cycle must carry their own @since
tag. The version number denotes the release version in which the element was/will be published the first time.
No empty lines
Empty lines in methods are discouraged. The desire to separate code blocks with empty lines is often an indication that a methods does more than one thing. Consider to extract these blocks into methods of their own.
An exception to this rule are unit tests. To visually emphasize the set up - execute - assert structure it is permitted to separate these with empty lines like in the example below:
public void testFoo() { Foo foo = new Foo() boolean actual = foo.bar(); assertTrue( actual ); }
Structuring test methods like this is inspired by Robert C. Martin's book Clean Code. See the BUILD-OPERATE-CHECK pattern in the chapter about unit testing.
Formatter and Code Template Settings
All relevant projects are configured with project-specific settings to use the formatter and code templates that are used by the RAP team.
Note: This formatter isn't able to cover all style conventions we use, but it helps to get started. We recommend not to run the formatter on the entire file, but to select a region of code to format. When you press Ctrl-Shift-F in the Java Editor while a section (e.g. a method) is selected, only this section will be formatted.
JavaScript Code
All RAP bundles that contain JavaScript files have a jshint configuration file. All JavaScript has to conform to these settings. It is recommanded to use the eclipse ide jshint plugin.