Changes between Version 3 and Version 4 of Ja:DevelopersGuide/StyleGuide

Timestamp:

2018-06-10T11:15:33+02:00 (7 years ago)

Author:

anonymous

Comment:

--

Ja:DevelopersGuide/StyleGuide

@@ -1 @@
-[[TranslatedPages(revision=21,outdated=Translation incomplete)]] 
+[[TranslatedPages(revision=34,outdated=Translation incomplete)]] 
 = 開発ガイドライン =
 
@@ -5 +5 @@
 
  * make sure the code is Java 8 compatible
+ * '''Document''' your code using inline comments and javadoc. Many people will thank you :)
+ * Try to avoid public fields
+ * JOSM has a lot of helper methods in the `Utils`, `GuiUtils`, `Geometry` ... classes. Use them if you need
+ * Check parameters. You can use `Objects.requireNonNull`.
+ * 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.
+
+=== Threading / Locking ===
+
+ * JOSM uses various locking mechanisms, depending on the object.
+ * 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.
+ * GUI components should only be modified in the EDT thread
+ * Prefer to use `SwingUtils.invokeLater` if you need to run anything on the UI thread
+ * 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).
+
+== How your formatting should look like ==
+
  * make sure there is no trailing white space
  * don't use multiple consecutive empty lines
- * JOSM uses 4 characters indentation and no tab stops
- * Document your code '''thoroughly'''. Many people will thank you :)
+ * 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").
+ * add curly brackets for each {{{if}}}, unless it is followed by {{{return}}} (or maybe {{{throw}}})
+ * 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:
+{{{
+  #!bash
+    # make sure build2 dir exists, if it does not run 'ant checkstyle-compile' before
+
+    svn diff --summarize | awk '{ print $2 }' | grep "^[a-z]" | xargs \
+      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
+        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
+    # or
+    git diff --name-only | xargs \
+      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
+        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
+}}}
 
 == How your javadoc should look like ==
  * The [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc style guide] is used as the base guide
  * {{{@since}}} is used for public classes and methods (visible to plugin developers) with the JOSM revision that introduced the element. Example: {{{@since 5408}}}
-   * {{{@since}}} is updated when a public method signature changes or if a class is renamed
+   * {{{@since}}} is updated / added when a public method signature changes or if a class is renamed.
    * {{{@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.
+   * 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}}}
+   * 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.
  * {{{@throws}}} is preferred to {{{@exception}}}
+ * 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:
+
+{{{
+    svn diff --summarize | awk '{ print $2 }' | xargs javadoc -d javadoc
+    # or
+    git diff --name-only | xargs javadoc -d javadoc
+}}}
 
 === Eclipseの設定 ===
-[[Image(DevelopersGuide/StyleGuide:styleguide_compiler_16.png,700px)]]
+[[Image(wiki:DevelopersGuide/StyleGuide:styleguide_compiler_16.png,700px)]]
 
-[[Image(DevelopersGuide/StyleGuide:ss1.png,700px)]]
+[[Image(wiki:DevelopersGuide/StyleGuide:ss1.png,700px)]]
 
-[[Image(DevelopersGuide/StyleGuide:ss2.png,700px)]]
+[[Image(wiki:DevelopersGuide/StyleGuide:ss2.png,700px)]]
 
-[[Image(DevelopersGuide/StyleGuide:ss3.png,700px)]]
+[[Image(wiki:DevelopersGuide/StyleGuide:ss3.png,700px)]]
 
 
 == 国際化 ==
 
- * make sure you use {{{tr(...)}}} for all localized strings 
-   {{{ 
+ * make sure you use {{{tr(...)}}} for all localized strings
+   {{{
    import import static org.openstreetmap.josm.tools.I18n.tr;
 
@@ -37 +75 @@
    throw new Exception(tr("error message always in tr()"));
 
-   // use tr(...) for labels, title, tooltip texts and the like 
+   // use tr(...) for labels, title, tooltip texts and the like
    //
    new JLabel(tr("Label always in tr()"));
@@ -54 +92 @@
    '''DO'''
    {{{new JLabel(tr("My Label {0}",labelId));}}}
-   
+
    Only exception: {{{+}}} can be used to break long lines of non-variable texts.
 
  * When using apostrophe, the following rules apply:
-   
+
    For all {{{tr}}} the apostrophe is special. (Like backslash in C)[[BR]]
    It needs to be escaped by another apostrophe:
 
    {{{new JButton(tr("Don''t press me more than {0} times!", n))}}}
+
+----
+Back to [wiki:/DevelopersGuide Developers Guide]