|
@@ -17,7 +17,7 @@ Our policies are not set-in-stone. They represent directions chosen at a point i
|
17
|
17
|
|
18
|
18
|
| Track Event | Policies to review |
|
19
|
19
|
|:------------|:-----------------|
|
20
|
|
-| Exercise added/updated | [Prefer instance methods](#prefer-instance-methods); [Avoid using final](#avoid-using-final); [Adhere to best practices](#adhere-to-best-practices); [Starter implementations](#starter-implementations); [Ignore noninitial tests](#ignore-noninitial-tests); [Multiple file submissions](#multiple-file-submissions); [Name test class after class under test](#name-test-class-after-class-under-test); [Add hint for the first exercises without starter implementation](#add-hint-for-the-first-exercises-without-starter-implementation); [Reference tutorial in the first exercises](#reference-tutorial-in-the-first-exercises)
|
|
20
|
+| Exercise added/updated | [Prefer instance methods](#prefer-instance-methods); [Avoid using final](#avoid-using-final); [Adhere to best practices](#adhere-to-best-practices); [Starter implementations](#starter-implementations); [Ignore noninitial tests](#ignore-noninitial-tests); [Multiple file submissions](#multiple-file-submissions); [Name test class after class under test](#name-test-class-after-class-under-test); [Add hint for the first exercises without starter implementation](#add-hint-for-the-first-exercises-without-starter-implementation); [Reference tutorial in the first exercises](#reference-tutorial-in-the-first-exercises); [Avoid returning null](#avoid-returning-null); [Use ExpectedException](#use-expectedexception)
|
21
|
21
|
| Track rearranged | [Starter implementations](#starter-implementations); [Multiple file submissions](#multiple-file-submissions) |
|
22
|
22
|
| New issue observed in track | [Good first patches](#good-first-patches) |
|
23
|
23
|
| "Good first patch" issue completed | [Good first patches](#good-first-patches) |
|
|
@@ -46,7 +46,33 @@ References: [[1](https://github.com/exercism/java/issues/178)], [[2](https://git
|
46
|
46
|
### Adhere to best practices
|
47
|
47
|
|
48
|
48
|
> Ensure that all Java code adheres to the best practices listed below:
|
49
|
|
-> - minimize the accessibility of classes and members ([Effective Java, item 13](http://jtechies.blogspot.com/2012/07/item-13-minimize-accessibility-of.html))
|
|
49
|
+> - Minimize the accessibility of classes and members ([Effective Java, item 13](http://jtechies.blogspot.com/2012/07/item-13-minimize-accessibility-of.html))
|
|
50
|
+> - Always use curly brackest in if statements. This makes your code easier to maintain and easier to read ([Oracle style guide, item 7.4](http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-142311.html#431))
|
|
51
|
+```java
|
|
52
|
+// Please do this
|
|
53
|
+if (condition) {
|
|
54
|
+ doSomething();
|
|
55
|
+}
|
|
56
|
+
|
|
57
|
+// Please don't do this
|
|
58
|
+if (condition)
|
|
59
|
+ doSomething();
|
|
60
|
+
|
|
61
|
+if (condition) doSomething();
|
|
62
|
+```
|
|
63
|
+> - Always put opening curly bracket not on a newline ([Oracle style guide, item 7.2](http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-142311.html#431))
|
|
64
|
+```java
|
|
65
|
+// Please do this
|
|
66
|
+for (int i = 0; i < 10; i++) {
|
|
67
|
+ ...
|
|
68
|
+}
|
|
69
|
+
|
|
70
|
+// Please don't do this
|
|
71
|
+for (int i = 0; i < 10; i++)
|
|
72
|
+{
|
|
73
|
+ ...
|
|
74
|
+}
|
|
75
|
+```
|
50
|
76
|
|
51
|
77
|
### Ignore noninitial tests
|
52
|
78
|
|
|
@@ -101,3 +127,34 @@ References: [[1](https://github.com/exercism/java/issues/1075)]
|
101
|
127
|
> Therefore any exercise with difficulty less than 3 should have a hints.md file which references [the hello world tutorial](https://github.com/exercism/java/blob/master/exercises/hello-world/TUTORIAL.md).
|
102
|
128
|
|
103
|
129
|
References: [[1](https://github.com/exercism/java/issues/1389)]
|
|
130
|
+
|
|
131
|
+### Avoid returning null
|
|
132
|
+
|
|
133
|
+> The [canonical data](https://github.com/exercism/problem-specifications/tree/master/exercises) for each exercise intentionally doesn't deal with error handling.
|
|
134
|
+> When an error has occured or a method can't return anything, the canonical data will just mark that as `"expected": null`.
|
|
135
|
+> This is because error handling varies from language to language, so the canonical data is leaving it up to each language track to decide how to deal with those situations.
|
|
136
|
+> It doesn't mean that the method needs to return `null`.
|
|
137
|
+
|
|
138
|
+> In Java it's considered bad practice to return `null`.
|
|
139
|
+> If you return `null` then the user of the method has to remember to check for `null` and they have to look at the implementation of the method to find out that this is necessary.
|
|
140
|
+
|
|
141
|
+> It's considered best practice to deal with errors and unexpected circumstances by throwing exceptions.
|
|
142
|
+> If you throw an exception then you force the user to deal with the problem.
|
|
143
|
+> You can either define your own exception (see [the triangle exercise](https://github.com/exercism/java/blob/master/exercises/triangle/.meta/src/reference/java/TriangleException.java) for an example) or use a predefined one (see [the collatz-conjecture exercise](https://github.com/exercism/java/blob/master/exercises/collatz-conjecture/src/test/java/CollatzCalculatorTest.java) for an example).
|
|
144
|
+
|
|
145
|
+> Another option is to use [Optionals](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html).
|
|
146
|
+> This can be more suitable if the case you want to deal with isn't an exceptional occurence, but rather an expected scenario, e.g. a search method not finding what it was searching for.
|
|
147
|
+> See [the word-search exercise](https://github.com/exercism/java/blob/master/exercises/word-search/src/test/java/WordSearcherTest.java) for an example where `Optional` is used.
|
|
148
|
+
|
|
149
|
+References: [[1](https://www.codebyamir.com/blog/stop-returning-null-in-java)]
|
|
150
|
+
|
|
151
|
+### Use ExceptedException
|
|
152
|
+
|
|
153
|
+> Some exercises expect exceptions to be thrown in the tests.
|
|
154
|
+> The exercises on this track are all using JUnit's [`ExpectedException`](http://junit.org/junit4/javadoc/4.12/org/junit/rules/ExpectedException.html) `@Rule` feature to support that instead of `@Test(expected = SomeException.class)`.
|
|
155
|
+> `ExpectedException` is more powerful than using the `@Test` annotation, since with `ExpectedException` you can also inspect the exception's error message and other properties.
|
|
156
|
+> To be consistent, please use `ExpectedException` whenever you expect an exception to be thrown.
|
|
157
|
+
|
|
158
|
+> See [the triangle tests](https://github.com/exercism/java/blob/master/exercises/triangle/src/test/java/TriangleTest.java) for an example of where `ExpectedException` is used.
|
|
159
|
+
|
|
160
|
+References: [[1](https://github.com/junit-team/junit4/wiki/Exception-testing)]
|