Changes between Version 36 and Version 37 of DevelopersGuide/StyleGuide


Ignore:
Timestamp:
2022-08-12T16:48:46+02:00 (3 years ago)
Author:
leni
Comment:

replace by ; {{{ by `; http by https

Legend:

Unmodified
Added
Removed
Modified

  • DevelopersGuide/StyleGuide

    v36 v37  
    77
    88 * make sure the code is Java 8 compatible
    9  * '''Document''' your code using inline comments and javadoc. Many people will thank you :)
     9 * **Document** your code using inline comments and javadoc. Many people will thank you :)
    1010 * Try to avoid public fields
    1111 * JOSM has a lot of helper methods in the `Utils`, `GuiUtils`, `Geometry` ... classes. Use them if you need
    … …  
    2626 * don't use multiple consecutive empty lines
    2727 * 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").
    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:
     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:
    3030{{{
    3131  #!bash
    … …  
    4242
    4343== How your javadoc should look like ==
    44  * The [http://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}}}
     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`
    5151 * 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:
    5252
    … …  
    6969== Internationalization ==
    7070
    71  * make sure you use {{{tr(...)}}} for all localized strings
     71 * make sure you use `tr(...)` for all localized strings
    7272   {{{
    7373   #!java
    … …  
    8585   }}}
    8686
    87  * never assemble localized messages with {{{+}}}. Use format
     87 * never assemble localized messages with `+`. Use format
    8888   placeholders instead.
    8989
    90    '''DONT'''
    91    {{{new JLabel(tr("My Label " + labelId));}}}
     90   **DONT**
     91   `new JLabel(tr("My Label " + labelId));`
    9292
    93    '''DO'''
    94    {{{new JLabel(tr("My Label {0}",labelId));}}}
     93   **DO**
     94   `new JLabel(tr("My Label {0}",labelId));`
    9595
    96    Only exception: {{{+}}} can be used to break long lines of non-variable texts.
     96   Only exception: `+` can be used to break long lines of non-variable texts.
    9797   The placeholders are mandatory in simple translations.
    9898
    … …  
    102102   }}}
    103103
    104  * A translation context can be set with {{{trc(...)}}}. Additional hints to translators are given by java comments at the function:
     104 * A translation context can be set with `trc(...)`. Additional hints to translators are given by java comments at the function:
    105105   {{{#!java
    106106   /* I18n: house number, street as parameter; place number first for visibility */
    … …  
    108108   }}}
    109109
    110  * Use {{{trn(...)}}} to let translators choose the language specific plural:
     110 * Use `trn(...)` to let translators choose the language specific plural:
    111111   {{{#!java
    112112   msg = trn("Object deleted", "Objects deleted", del.size();