-
Notifications
You must be signed in to change notification settings - Fork 263
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #903 from RPTools/release-1.5.7
Release 1.5.7 back to master.
- Loading branch information
Showing
100 changed files
with
3,471 additions
and
1,333 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| files: | ||
| - source: /src/main/resources/net/rptools/maptool/language/i18n.properties | ||
| translation: /%original_path%/%file_name%_%two_letters_code%.%file_extension% |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,26 @@ | ||
| # Code Style and Guidelines | ||
|
|
||
| Please follow the following rules when working on MapTool. Failure to follow these will typically result in your patch being rejected. | ||
| Please observe the following rules when working on MapTool. Failure to do so will typically result in your pull request being rejected. | ||
|
|
||
| For now patches should be posted to the Testers forum. Access to that forum is by request only; send a PM to [jfrazierjr](http://forums.rptools.net/memberlist.php?mode=viewprofile&u=773) here on the [forums](http://forums.rptools.net/) and he'll add you to the group. You may then visit that hidden forum and review information on how to post patches for submission. | ||
|
|
||
| 1. Thou shalt always highlight the content of any Java source code thee hath modified and select **Source -> Format**. Note: this requires that the user reset the line length in the Eclipse properties: Trevor wants the line length set to 200 characters. *(But see the attached preferences import file as the formatting settings are implemented there.)* | ||
| 2. Thou shalt always select **Source -> Reorganize Imports.** | ||
| 3. Thou shalt always submit code that includes Javadoc comments for public classes and methods. (T'would be nice to require full Javadoc for everything, but alas, that is unlikely.) | ||
| 4. Thou shalt always use the `/* */` style of comments in front of classes and methods and may use single-line comments in front of member variables and small snippets of code, but **See Rule #3**! | ||
| 5. Thou shalt always use parameter names different from member field names so that disambiguation using **this** is not necessary. *(Exception: code generated by Eclipse's Source menu items is exempt from this requirement as a productivity enhancement.)* | ||
| 6. Thou shalt always clearly delineate private constructors with comments so that those who come after thee may retain thy sanity. | ||
| 7. Thou shalt never use hard-coded strings in code when a property from an external file can be used. (In MapTool's case, this means calling `I18N.getText(propertyKey)` and adding a definition for the `propertyKey` to `i18n.properties`. Also, all of the `show*()` methods in MapTool, such as `showError()` and `showWarning()`, take `propertyKeys` as well as strings -- only use `propertyKeys`!) | ||
| 8. Thou shalt always use `static final String` when hard-coded strings _are_ appropriate. Examples include resources that are embedded inside the MapTool JAR, such as **unknown.png** -- the question mark image. Other image names that may be considered part of the "theme", such as toolbar images, button images, and so forth, should be retrieved from an images property file; I propose `images.properties` since we already have `sounds.properties`. A string in the code should reference a pathname in the property file. | ||
| 9. Thou shalt report all exceptions that are true errors. `InterruptedException` while waiting for a timer can be ignored, for example. But all other errors should be handled by calling `MapTool.showError(propertyKey)` or similar and passing both a `propertyKey` and the `Throwable` object representing the exception. Note that the various "show" methods already provide logging to the `.maptool/log.txt` file, but separate logging should be performed in the class if possible, since the XML configuration is an all-or-nothing for `net.rptools.maptool.client.MapTool`. | ||
| 10. Thou shalt always use defined properties instead of hard-coded strings when possible. Such as `File.separator` instead of **"/"** and now `AppActions.menuShortcut` instead of **"ctrl"**. | ||
| 1. The [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) is incorporated by reference. Submitted code shall follow those guidelines unless modified by one or more of the following rules. | ||
| 2. Use parameter names different from member field names so that disambiguation using **this** is not necessary. This rule is relaxed for simple short methods (e.g. setters). | ||
| 3. Avoid hard-coded strings in code when a property from an external file can be used. In MapTool's case, this means calling `I18N.getText(propertyKey)` and adding a definition for the `propertyKey` to `i18n.properties`. Also, all of the `show*()` methods in MapTool, such as `showError()` and `showWarning()`, take `propertyKeys` as well as strings -- only use `propertyKeys`!) | ||
| 4. Use `static final String` when hard-coded strings _are_ appropriate. Examples include resources that are embedded inside the MapTool JAR, such as **unknown.png** -- the question mark image. | ||
| 5. Report to the user all exceptions that are true errors. `InterruptedException` while waiting for a timer can be ignored, for example. But all other errors should be handled by calling `MapTool.showError(propertyKey)` or similar and passing both a `propertyKey` and the `Throwable` object representing the exception. Note that the various "show" methods already provide logging to the `.maptool/log.txt` file. | ||
| 6. Use the language-defined static variables instead of hard-coded strings when possible. Examples include `File.separator` instead of **"/"** and `AppActions.menuShortcut` instead of **"ctrl"**. | ||
|
|
||
| There are surely others that you (the contributors) may want added and that we (the dev team) determine to be acceptable. Please speak up. :) | ||
|
|
||
| An exported set of Eclipse Preferences as a ZIP file is available [here](http://forums.rptools.net/download/file.php?id=4151). Unpack the ZIP and use **File > Import...** to read them. These preferences only include Java appearance and style-related settings, plus Task tag definitions. (Keyboard shortcuts and other settings are left untouched.) | ||
| ## Formatting Source Files | ||
|
|
||
| ### Formatting with your IDE | ||
| Most IDEs include some Source Formatting functionality and using that functionality can make following the guidelines easier. You will need to ensure that using any such functionality does follow the guidelines. | ||
|
|
||
| Example for Eclipse: | ||
| * Source -> Format | ||
| * Source -> Reorganize Imports | ||
|
|
||
| An exported set of Eclipse Preferences can be found in the GitHub repo under `build-resources/eclipse`. Other IDEs/editors may be able to import those preference files. If you create one for your preferred environment, you can always create a Pull Request to submit it to the MapTool repo. | ||
|
|
||
| ### Formatting with Spotless | ||
| The gradle build file for MapTool includes the Spotless targets: spotlessCheck and spotlessApply. Make use of them by doing a `gradlew spotlessCheck` and/or `spotlessApply` prior to committing or pushing your changes. Spotless will enforce the majority of the rules but not all. |
Oops, something went wrong.