Changes between Version 33 and Version 38 of DevelopersGuide/StyleGuide


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

Legend:

Unmodified
Added
Removed
Modified

  • DevelopersGuide/StyleGuide

    v33 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{{{
    29     svn diff --summarize | awk '{ print $2 }' | xargs java -jar tools/checkstyle/checkstyle-7.1-all.jar -c tools/checkstyle/josm_checks.xml
     31  #!bash
     32    # make sure build2 dir exists, if it does not run 'ant checkstyle-compile' before
     33
     34    svn diff --summarize | awk '{ print $2 }' | grep "^[a-z]" | xargs \
     35      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
     36        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
    3037    # or
    31     git diff --name-only | xargs java -jar tools/checkstyle/checkstyle-7.1-all.jar -c tools/checkstyle/josm_checks.xml
     38    git diff --name-only | xargs \
     39      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
     40        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
    3241}}}
    3342
    3443== How your javadoc should look like ==
    35  * The [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc style guide] is used as the base guide
    36  * {{{@since}}} is used for public classes and methods (visible to plugin developers) with the JOSM revision that introduced the element. Example: {{{@since 5408}}}
    37    * {{{@since}}} is updated / added when a public method signature changes or if a class is renamed.
    38    * {{{@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.
    39    * 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}}}
    40    * 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.
    41  * {{{@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`
    4251 * 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:
    4352
    … …  
    6069== Internationalization ==
    6170
    62  * make sure you use {{{tr(...)}}} for all localized strings
     71 * make sure you use `tr(...)` for all localized strings
    6372   {{{
     73   #!java
    6474   import import static org.openstreetmap.josm.tools.I18n.tr;
    6575
    … …  
    7585   }}}
    7686
    77 
    78  * never assemble localized messages with {{{+}}}. Use format
     87 * never assemble localized messages with `+`. Use format
    7988   placeholders instead.
    8089
    81    '''DONT'''
    82    {{{new JLabel(tr("My Label " + labelId));}}}
     90   **DONT**
     91   `new JLabel(tr("My Label " + labelId));`
    8392
     93   **DO**
     94   `new JLabel(tr("My Label {0}",labelId));`
    8495
    85    '''DO'''
    86    {{{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.
    8798
    88    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   }}}
    89103
    90  * 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   }}}
    91109
    92    For all {{{tr}}} the apostrophe is special. (Like backslash in C)[[BR]]
    93    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))
    94118
    95    {{{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.
    96127
    97128----
    98 Back to [wiki:/DevelopersGuide Developers Guide]
     129Back to [wikitr:/DevelopersGuide Developers Guide]