| 6 | | * make sure the code is Java 7 compatible |
| | 8 | * make sure the code is Java 11 compatible |
| | 9 | * **Document** your code using inline comments and javadoc. Many people will thank you :) |
| | 10 | * Try to avoid public fields |
| | 11 | * JOSM has a lot of helper methods in the `Utils`, `GuiUtils`, `Geometry` ... classes. Use them if you need |
| | 12 | * Check parameters. You can use `Objects.requireNonNull`. |
| | 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. |
| | 14 | |
| | 15 | === Threading / Locking === |
| | 16 | |
| | 17 | * JOSM uses various locking mechanisms, depending on the object. |
| | 18 | * The data sets are protected by a RW lock. Some methods do not automatically lock for performance reasons. Make sure to acquire the locks required for your changes. |
| | 19 | * GUI components should only be modified in the EDT thread |
| | 20 | * Prefer to use `SwingUtils.invokeLater` if you need to run anything on the UI thread |
| | 21 | * Many listeners already run in the EDT thread (layer changes) or have a central manager that allows you to register listeners that run in EDT (dataset changes, selection changes). |
| | 22 | |
| | 23 | == How your formatting should look like == |
| | 24 | |
| 9 | | * JOSM uses 4 characters indentation and no tab stops |
| 10 | | * Document your code '''thoroughly'''. Many people will thank you :) |
| | 27 | * 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: |
| | 30 | {{{ |
| | 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 |
| | 37 | # or |
| | 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 |
| | 41 | }}} |
| 13 | | * The [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc style guide] is used as the base guide |
| 14 | | * {{{@since}}} is used for public classes and methods (visible to plugin developers) with the JOSM revision that introduced the element. Example: {{{@since 5408}}} |
| 15 | | * {{{@since}}} is updated when a public method signature changes or if a class is renamed |
| 16 | | * {{{@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. |
| 17 | | * {{{@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` |
| | 51 | * 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: |
| | 52 | |
| | 53 | {{{ |
| | 54 | svn diff --summarize | awk '{ print $2 }' | xargs javadoc -d javadoc |
| | 55 | # or |
| | 56 | git diff --name-only | xargs javadoc -d javadoc |
| | 57 | }}} |
| 54 | | '''DO''' |
| 55 | | {{{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. |
| | 98 | |
| | 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 | }}} |
| | 103 | |
| | 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 | }}} |
| | 109 | |
| | 110 | * Use `trn(...)` to let translators choose the language specific plural: |
| | 111 | {{{#!java |
| | 112 | msg = trn("Object deleted", "Objects deleted", del.size(); |
| 59 | | * When using apostrophe, the following rules apply: |
| 60 | | |
| 61 | | For all {{{tr}}} the apostrophe is special. (Like backslash in C)[[BR]] |
| 62 | | It needs to be escaped by another apostrophe: |
| | 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 | }}} |
