Merge pull request #1416 from FridaTveit/UpdatePolicies

Update policies

POLICIES.md

@@ -17,7 +17,7 @@ Our policies are not set-in-stone. They represent directions chosen at a point i
 
 | Track Event | Policies to review |
 |:------------|:-----------------|
-| 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)
+| 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)
 | Track rearranged | [Starter implementations](#starter-implementations); [Multiple file submissions](#multiple-file-submissions) |
 | New issue observed in track | [Good first patches](#good-first-patches) |
 | "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
 ### Adhere to best practices
 
 > Ensure that all Java code adheres to the best practices listed below:
-> - minimize the accessibility of classes and members ([Effective Java, item 13](http://jtechies.blogspot.com/2012/07/item-13-minimize-accessibility-of.html))
+> - Minimize the accessibility of classes and members ([Effective Java, item 13](http://jtechies.blogspot.com/2012/07/item-13-minimize-accessibility-of.html))
+> - 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))
+```java
+// Please do this
+if (condition) {
+    doSomething();
+}
+
+// Please don't do this
+if (condition)
+    doSomething();
+
+if (condition) doSomething();
+```
+> - 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))
+```java
+// Please do this
+for (int i = 0; i < 10; i++) {
+    ...
+}
+
+// Please don't do this
+for (int i = 0; i < 10; i++)
+{
+    ...
+}
+```
 
 ### Ignore noninitial tests
 
@@ -101,3 +127,34 @@ References: [[1](https://github.com/exercism/java/issues/1075)]
 > 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).
 
 References: [[1](https://github.com/exercism/java/issues/1389)]
+
+### Avoid returning null
+
+> The [canonical data](https://github.com/exercism/problem-specifications/tree/master/exercises) for each exercise intentionally doesn't deal with error handling.
+> When an error has occured or a method can't return anything, the canonical data will just mark that as `"expected": null`.
+> 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.
+> It doesn't mean that the method needs to return `null`.
+
+> In Java it's considered bad practice to return `null`.
+> 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.
+
+> It's considered best practice to deal with errors and unexpected circumstances by throwing exceptions.
+> If you throw an exception then you force the user to deal with the problem.
+> 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).
+
+> Another option is to use [Optionals](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html).
+> 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.
+> 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.
+
+References: [[1](https://www.codebyamir.com/blog/stop-returning-null-in-java)]
+
+### Use ExceptedException
+
+> Some exercises expect exceptions to be thrown in the tests.
+> 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)`.
+> `ExpectedException` is more powerful than using the `@Test` annotation, since with `ExpectedException` you can also inspect the exception's error message and other properties.
+> To be consistent, please use `ExpectedException` whenever you expect an exception to be thrown.
+
+> 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.
+
+References: [[1](https://github.com/junit-team/junit4/wiki/Exception-testing)]