Changes between Version 34 and Version 38 of DevelopersGuide/StyleGuide


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified

  • DevelopersGuide/StyleGuide

    v34 v38  
    22= Development Guidelines =
    33
     4[[PageOutline(2-2,Table of content,inline)]]
     5
    46== How your code should look like ==
    57
    6  * make sure the code is Java 8 compatible
    7  * '''Document''' your code using inline comments and javadoc. Many people will thank you :)
     8 * make sure the code is Java 11 compatible
     9 * **Document** your code using inline comments and javadoc. Many people will thank you :)
    810 * Try to avoid public fields
    911 * JOSM has a lot of helper methods in the `Utils`, `GuiUtils`, `Geometry` ... classes. Use them if you need
    1012 * Check parameters. You can use `Objects.requireNonNull`.
    11  * Don't write for performance - write for readability. Use `Stream`s, `Function`s and other Java 8 features if they make the code more readable.
     13 * Don't write for performance - write for readability. Use `Stream`s, `Function`s and other Java 8+ features if they make the code more readable.
    1214
    1315=== Threading / Locking ===
    … …  
    2426 * don't use multiple consecutive empty lines
    2527 * JOSM uses 4 characters indentation and no tab stops. If you use Notepad++ you can change the default indentation in the "Preferences" -> "Language" -> "Tab Settings" -> check "Replace by spaces" (this is permanent) or with the "change indentation settings" button in the toolbar (this is a temopary setting and requires the plugin "Customize Toolbar").
    26  * add curly brackets for each {{{if}}}, unless it is followed by {{{return}}} (or maybe {{{throw}}})
    27  * You should use '''checkstyle''' before patch/commit: `ant checkstyle` and check `checkstyle-josm.xml`; if you find running checkstyle slow for all files, run for changed files only:
     28 * add curly brackets for each `if`, unless it is followed by `return` (or maybe `throw`)
     29 * You should use **checkstyle** before patch/commit: `ant checkstyle` and check `checkstyle-josm.xml`; if you find running checkstyle slow for all files, run for changed files only:
    2830{{{
    2931  #!bash
    … …  
    4042
    4143== How your javadoc should look like ==
    42  * The [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc style guide] is used as the base guide
    43  * {{{@since}}} is used for public classes and methods (visible to plugin developers) with the JOSM revision that introduced the element. Example: {{{@since 5408}}}
    44    * {{{@since}}} is updated / added when a public method signature changes or if a class is renamed.
    45    * {{{@since}}} can be omitted for public methods and fields introduced at the same time as the class, provided they do not have changed and the class is correctly documented.
    46    * There can be multiple {{{@since}}} tags, e.g. for adding interfaces to a class. The reason for those tags should be added Example: {{{@since 12345 @FunctionalIterface was added}}}
    47    * If you submit a patch and don't know the revision, add {{{@since xxx}}} any way. It can then be replaced when merging your patch.
    48  * {{{@throws}}} is preferred to {{{@exception}}}
     44 * The [https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc style guide] is used as the base guide
     45 * `@since` is used for public classes and methods (visible to plugin developers) with the JOSM revision that introduced the element. Example: `@since 5408`
     46   * `@since` is updated / added when a public method signature changes or if a class is renamed.
     47   * `@since` can be omitted for public methods and fields introduced at the same time as the class, provided they do not have changed and the class is correctly documented.
     48   * There can be multiple `@since` tags, e.g. for adding interfaces to a class. The reason for those tags should be added Example: `@since 12345 @FunctionalIterface was added`
     49   * If you submit a patch and don't know the revision, add `@since xxx` any way. It can then be replaced when merging your patch.
     50 * `@throws` is preferred to `@exception`
    4951 * check your changes before patch/commit by generating javadoc: `ant javadoc`, browse output messages; if you find running javadoc slow for all files, run for changed files only:
    5052
    … …  
    6769== Internationalization ==
    6870
    69  * make sure you use {{{tr(...)}}} for all localized strings
     71 * make sure you use `tr(...)` for all localized strings
    7072   {{{
     73   #!java
    7174   import import static org.openstreetmap.josm.tools.I18n.tr;
    7275
    … …  
    8285   }}}
    8386
    84 
    85  * never assemble localized messages with {{{+}}}. Use format
     87 * never assemble localized messages with `+`. Use format
    8688   placeholders instead.
    8789
    88    '''DONT'''
    89    {{{new JLabel(tr("My Label " + labelId));}}}
     90   **DONT**
     91   `new JLabel(tr("My Label " + labelId));`
    9092
     93   **DO**
     94   `new JLabel(tr("My Label {0}",labelId));`
    9195
    92    '''DO'''
    93    {{{new JLabel(tr("My Label {0}",labelId));}}}
     96   Only exception: `+` can be used to break long lines of non-variable texts.
     97   The placeholders are mandatory in simple translations.
    9498
    95    Only exception: {{{+}}} can be used to break long lines of non-variable texts.
     99 * When using apostrophe in the source string, it needs to be escaped by another apostrophe (Like backslash in C):[[BR]]
     100   {{{#!java
     101   new JButton(tr("Don''t press me!"))
     102   }}}
    96103
    97  * When using apostrophe, the following rules apply:
     104 * A translation context can be set with `trc(...)`. Additional hints to translators are given by java comments at the function:
     105   {{{#!java
     106   /* I18n: house number, street as parameter; place number first for visibility */
     107   msg = tr("House number {0} at {1}", s, t);
     108   }}}
    98109
    99    For all {{{tr}}} the apostrophe is special. (Like backslash in C)[[BR]]
    100    It needs to be escaped by another apostrophe:
     110 * Use `trn(...)` to let translators choose the language specific plural:
     111   {{{#!java
     112   msg = trn("Object deleted", "Objects deleted", del.size();
     113   
     114   // or with placeholders:
     115   //
     116   new JButton(trn(/* I18n: times needed, some name as parameter */
     117                       "Press {1} {0} times!", n, n, someName))
    101118
    102    {{{new JButton(tr("Don''t press me more than {0} times!", n))}}}
     119   // The English singular source string must be given for identification
     120   // even when its logically invalid and won't occur. For consistency
     121   // the number placeholder should be set in it.
     122   //
     123   msg = trn("Combine {0} way", "Combine {0} ways", n, n);
     124   }}}
     125
     126 In plural segments no placeholder is mandatory for translators.
    103127
    104128----
    105 Back to [wiki:/DevelopersGuide Developers Guide]
     129Back to [wikitr:/DevelopersGuide Developers Guide]