| 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 (If you use Notepad++ you can change the default indentation in the "Preferences" -> "Tab Settings" -> check "Replace by spaces" (this is permanent) or with the "change indentation settings" button in the toolbar by removing the check at "use tabs" (this is a temopary setting).) |
| 10 | | * Document your code '''thoroughly'''. Many people will thank you :) |
| 11 | | * add curly brackets for each {{{if}}}, unless it is followed by {{{return}}} (or maybe {{{throw}}}) |
| 12 | | * check your changes before patch/commit: `ant checkstyle` and check `checkstyle-josm.xml`; if you find running checkstyle slow for all files, run for changed files only: |
| | 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 |
| 21 | | * The [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc style guide] is used as the base guide |
| 22 | | * {{{@since}}} is used for public classes and methods (visible to plugin developers) with the JOSM revision that introduced the element. Example: {{{@since 5408}}} |
| 23 | | * {{{@since}}} is updated when a public method signature changes or if a class is renamed |
| 24 | | * {{{@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. |
| 25 | | * {{{@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` |
| 76 | | For all {{{tr}}} the apostrophe is special. (Like backslash in C)[[BR]] |
| 77 | | 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)) |
