Add Java stub

rules/0250-Java.md

@@ -1 +1,46 @@
-<!--- this is only a placeholder -->
+## Java
+*Note:* This section is under construction and could use some help. Please
+submit pull-requests.
+
+### Beware of the assert arguments!
+JUnit differs from the other frameworks. Very. Much. Well, overall it doesn't,
+it still has `assertEquals`, `assertArrayEquals` and others. But the
+order of arguments is swapped.
+
+Where CoffeeScript, Ruby, Python and Haskell expect the first argument of
+`Test.assert_equals`/`Test.assertEquals`/`shouldBe` to be the actual value and
+the second to be the expected, JUnit swaps the order, see the documentation of
+[Assert][assert-java]:
+
+``` java
+assertEquals(double expected, double actual); // note: use delta variant!
+assertEquals(float  expected, float  actual); // note: use delta variant!
+assertEquals(long   expected, long   actual);
+// many other
+```
+
+For comparison, here's the syntax of an equality assert in the other languages:
+
+``` haskell
+-- Haskell
+actual `shouldBe` expected
+```
+``` javascript
+// Javascript
+Test.assertEquals(actual, expected, message);
+```
+``` python
+# Python
+Test.assert_equals(actual, expected, message)
+```
+``` ruby
+# Ruby
+Test.assert_equals(actual, expected, message)
+```
+
+Keep this in mind. Your tests won't fail on correct solutions if you swap the
+arguments, but they __will__ confuse anyone who fails them. By the way, CSharp
+uses the same convention. This isn't surprising, since its testing framework
+NUnit was inspired by JUnit.
+
+ [assert-java]: http://junit.org/javadoc/latest/org/junit/Assert.html