Difference between revisions of "RAP/CodingStandards"

From Eclipsepedia

< RAP
Jump to: navigation, search
(added JavaScript chapter)
(21 intermediate revisions by 7 users not shown)
Line 1: Line 1:
'''Coding Conventions'''
+
This document describes the coding conventions used by the RAP project.
  
This document describes the basic Coding Conventions used by the RAP development team.
+
'''Note''': These conventions affect only code created by the RAP project. RAP reuses a lot of code from RCP (currently by copying that code) - this code is not re-formatted.
  
'''Note''': These conventions affect only newly created code. RAP reuses a lot of code from RCP (currently by copying that code) - These code-snippets are normally not re-formatted.
+
We follow the Sun conventions for the Java language: http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.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:
  
 +
== General rules for text files ==
  
Follow the Sun conventions for the Java language: http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.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:
+
==== Unix newlines ====
 +
Text files must use only Unix line delimiters (<code>\n</code>).
  
 +
==== UTF-8 ====
 +
If files contain non-ASCII characters, they have to be UTF-8 encoded.
  
* Method parameters (with the exception of abstract methods) are never assigned to and have to be declared as final
+
==== No TABs ====
* There must be at most one return statement in each method
+
We use spaces only to indent. TAB characters are forbidden in RAP source files.
* Do not use continue, break or return statements in loops
+
* Use for loops if there is a known number of iterations in the loop, else use while loops (i.e.: don't use for loops with a list iterator)
+
* Do not use variable names with only one letter (except loop variables in loops)
+
* 80 characters per line is maximum
+
* TAB characters are forbidden
+
* Text files must use Unix line delimiters
+
* Insert a space after opening braces and before closing braces (i.e.: if( someMethod( arg1, arg2 ) == array [ i ] ) { ... )
+
* If lines are broken at an operator, the operator must be on the next line, and the next line is indented once. (No naked operators at the end of a line)
+
* All public API must be marked with a <code>@since</code> tag at the class/interface level. Only methods, fields etc. that are added in a later release cycle must carry their own <code>@since</code> tag. The version number denotes the *release* version in which the element was/will be published the first time.
+
  
 +
==== 100 chars per line ====
 +
We just decided to extend the line length from 80 to 100 characters.
 +
This is a hard limit.
  
'''Codeformatter Template'''
+
== Java code ==
  
The following XML snippet contains the codeformatter configurations for Eclipse used by the RAP team. To use it copy the content, save it to a file named codeformatter.xml and import the template with the Code Template preference page.
+
==== Spaces inside braces ====
 +
Insert a space after opening braces and before closing braces. Examples:
 +
if( value == array[ i ] ) {
 +
  someMethod( arg1, arg2 );
 +
}
  
'''Note''': This template isn't able to cover all style conventions we use, but it helps to get started.
+
while( count <= maxNumber ) {
 +
  ...
  
<pre>
+
==== Linebreak before operators ====
<?xml version="1.0" encoding="UTF-8"?>
+
If lines are broken at an operator, the operator must be on the next line, and the next line is indented once.
<profiles version="5">
+
There must be no naked operators at the end of a line. Example:
<profile name="rap" version="5">
+
<setting id="comment_clear_blank_lines" value="true"/>
+
<setting id="comment_format_comments" value="true"/>
+
<setting id="comment_format_header" value="true"/>
+
<setting id="comment_format_html" value="true"/>
+
<setting id="comment_format_source_code" value="true"/>
+
<setting id="comment_indent_parameter_description" value="true"/>
+
<setting id="comment_indent_root_tags" value="true"/>
+
<setting id="comment_line_length" value="80"/>
+
<setting id="comment_new_line_for_parameter" value="false"/>
+
<setting id="comment_separate_root_tags" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.align_type_members_on_columns" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression" value="82"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call" value="82"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation" value="82"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression" value="82"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression" value="50"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_compact_if" value="52"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_conditional_expression" value="51"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer" value="52"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields" value="16"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration" value="82"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration" value="82"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation" value="84"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superclass_in_type_declaration" value="36"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration" value="36"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration" value="36"/>
+
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="36"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_imports" value="1"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_package" value="1"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_field" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_first_class_body_declaration" value="1"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_imports" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_member_type" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_method" value="1"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_new_chunk" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_package" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_type_declarations" value="1"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_anonymous_type_declaration" value="next_line_on_wrap"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block" value="next_line_on_wrap"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration" value="next_line_on_wrap"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_method_declaration" value="next_line_on_wrap"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
+
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_type_declaration" value="next_line_on_wrap"/>
+
<setting id="org.eclipse.jdt.core.formatter.compact_else_if" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.continuation_indentation" value="2"/>
+
<setting id="org.eclipse.jdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
+
<setting id="org.eclipse.jdt.core.formatter.filling_space" value=" "/>
+
<setting id="org.eclipse.jdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_type_header" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.indent_breaks_compare_to_cases" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_block" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_body" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_closing_brace_in_array_initializer" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_control_statements" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_anonymous_type_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_method_body" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_type_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_paren_in_cast" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_assert" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_allocation_expression" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_parameters" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_throws" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_explicitconstructorcall_arguments" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_increments" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_inits" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_field_declarations" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_local_declarations" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_superinterfaces" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_allocation_expression" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_reference" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_cast" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_catch" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_constructor_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_for" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_if" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_switch" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_synchronized" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_while" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_allocation_expression" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_reference" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_cast" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_catch" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_constructor_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_for" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_if" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_switch" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_synchronized" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_while" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_assert" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_allocation_expression" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_parameters" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_throws" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_explicitconstructorcall_arguments" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_increments" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_inits" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_field_declarations" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_local_declarations" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_superinterfaces" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_anonymous_type_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_constructor_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_allocation_expression" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_reference" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_type_reference" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_catch" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_constructor_declaration" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_for" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_if" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_switch" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_synchronized" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_while" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_brackets_in_array_type_reference" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_brackets_in_array_allocation_expression" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_constructor_declaration" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
+
<setting id="org.eclipse.jdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.lineSplit" value="80"/>
+
<setting id="org.eclipse.jdt.core.formatter.number_of_blank_lines_at_beginning_of_method_body" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.number_of_empty_lines_to_preserve" value="0"/>
+
<setting id="org.eclipse.jdt.core.formatter.preserve_user_linebreaks" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.put_empty_statement_on_new_line" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.remove_unnecessary_semicolon" value="false"/>
+
<setting id="org.eclipse.jdt.core.formatter.tabulation.char" value="space"/>
+
<setting id="org.eclipse.jdt.core.formatter.tabulation.size" value="2"/>
+
</profile>
+
</profiles>
+
  
</pre>
+
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.
 +
 
 +
==== No multiple returns ====
 +
A method must not have more than one return statement.
 +
For example, instead of:
 +
 
 +
public boolean isReady() {
 +
  if( processor != null ) {
 +
    return processor.isInitialized(); <strong>// BAD</strong>
 +
  }
 +
  return false;
 +
}
 +
 
 +
write this:
 +
 
 +
public boolean isReady() {
 +
  boolean result = false;
 +
  if( processor != null ) {
 +
    result = processor.isInitialized();
 +
  }
 +
  return result;
 +
}
 +
 
 +
==== No dirty exit ====
 +
It is not allowed to exit a loop using <code>continue</code>, <code>break</code> or <code>return</code> statements.
 +
For example, this code:
 +
 
 +
for( int i = 0; i < values.length; i++ ) {
 +
  if( values[ i ] == wanted ) {
 +
    found = true;
 +
    break; <strong>// BAD</strong>
 +
  }
 +
}
 +
 
 +
can also be written without the <code>break</code>:
 +
 
 +
for( int i = 0; i < values.length<strong> && !found</strong>; i++ ) {
 +
  if( values[ i ] == wanted ) {
 +
    found = true;
 +
  }
 +
}
 +
 
 +
==== 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; <strong>// BAD</strong>
 +
 
 +
but instead:
 +
 
 +
int count = 0;
 +
int line = 1;
 +
 
 +
==== No misused <code>for</code> loops ====
 +
Use <code>for</code> loops ''only'' if there is a known number of iterations in the loop, otherwise use <code>while</code> loops.
 +
Particularly, don't use <code>for</code> loops to iterate over a list iterator.
 +
 
 +
==== <code>@since</code> Tags ====
 +
All public API must be marked with a <code>@since</code> tag at the class/interface level. Only methods, fields etc. that are added in a later release cycle must carry their own <code>@since</code> 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 not permitted. The desire to separate blocks with empty lines is often a sign for too long methods. Extract them into methods of their own.
 +
 
 +
An exception thereof are test methods. 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.
 +
 
 +
[http://eclipse.org/rap/resources/rap-java-formatter.xml download formatter]
 +
 
 +
== 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 [http://github.eclipsesource.com/jshint-eclipse/ eclipse ide jshint plugin].
  
 
[[Category:RAP]]
 
[[Category:RAP]]

Revision as of 06:25, 3 July 2012

This document describes the coding conventions used by the RAP project.

Note: These conventions affect only code created by the RAP project. RAP reuses a lot of code from RCP (currently by copying that code) - this code is not re-formatted.

We follow the Sun conventions for the Java language: http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.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.

No multiple returns

A method must not have more than one return statement. For example, instead of:

public boolean isReady() {
  if( processor != null ) {
    return processor.isInitialized(); // BAD
  }
  return false;
}

write this:

public boolean isReady() {
  boolean result = false;
  if( processor != null ) {
    result = processor.isInitialized();
  }
  return result;
}

No dirty exit

It is not allowed to exit a loop using continue, break or return statements. For example, this code:

for( int i = 0; i < values.length; i++ ) {
  if( values[ i ] == wanted ) {
    found = true;
    break; // BAD
  }
}

can also be written without the break:

for( int i = 0; i < values.length && !found; i++ ) {
  if( values[ i ] == wanted ) {
    found = true;
  }
}

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 not permitted. The desire to separate blocks with empty lines is often a sign for too long methods. Extract them into methods of their own.

An exception thereof are test methods. 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.

download formatter

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.