Jump to: navigation, search

Difference between revisions of "RAP/CodingStandards"

< RAP
(set code example in monospace)
Line 22: Line 22:
  
  
'''Codeformatter Template'''
+
'''Formatter and Code Template Settings'''
  
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.
+
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 template isn't able to cover all style conventions we use, but it helps to get started.
+
'''Note''': This formatter isn't able to cover all style conventions we use, but it helps to get started.
  
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<profiles version="5">
 
<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>
 
  
 
[[Category:RAP]]
 
[[Category:RAP]]

Revision as of 03:53, 4 July 2008

Coding Conventions

This document describes the basic Coding Conventions used by the RAP development team.

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.


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:


  • Method parameters (with the exception of abstract methods) are never assigned to and have to be declared as final
  • There must be at most one return statement in each method
  • 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 @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.


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.