From 2eff23e5f5777ec883fe4aa014f92f9bbecaa6f6 Mon Sep 17 00:00:00 2001
From: "Damith C. Rajapakse" <damith@gmail.com>
Date: Fri, 27 Jan 2017 17:51:36 +0800
Subject: [PATCH] Java: add guidelines for using  assertions

We have a Java coding standard to specify syntax level guidelines.
Higher level guidelines such as when to use assertions are not documented.

Let's add a document to specify those additional guidelines for Java.
Include in that document guidelines for using assertions.
---
 codingStandards/AdditionalGuidelines-Java.md | 44 ++++++++++++++++++++
 docs/CodingStandards.md                      |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 codingStandards/AdditionalGuidelines-Java.md

diff --git a/codingStandards/AdditionalGuidelines-Java.md b/codingStandards/AdditionalGuidelines-Java.md
new file mode 100644
index 0000000..231c43d
--- /dev/null
+++ b/codingStandards/AdditionalGuidelines-Java.md
@@ -0,0 +1,44 @@
+# Additional Guidelines - Java
+
+## Using assertions
+
+Refer to the article 
+_[Programming With Assertions](http://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html)_ 
+(from Oracle) for more details on the three general guidelines below.
+
+1. **Do not use assertions to do any work that your application requires for correct operation.**<br> 
+   If you do, the code will not work as expected when assertions are turned off.
+   
+   
+1. **Do not use assertions for checking _preconditions_/parameters in public methods.**<br> 
+   Those should be enforced by explicit checks that throw particular, 
+   specified exceptions. e.g. `IllegalArgumentException`, `IndexOutOfBoundsException`, or `NullPointerException`.
+   
+   
+1. **Assertions may be used to check _postconditions_ and class/method _invariants_ in both public 
+   and nonpublic methods.**
+
+In addition,
+
+* **Do not handle 'impossible' exceptions using assertions**.<br> 
+  Instead of handling 'impossible' exceptions using an `assert false` as given below, 
+  throw a runtime error such as an `AssertionError`.
+
+  ![](Bad.png)
+  ```java
+   ...
+   } catch (Exception e) {
+       assert false : "This exception should not happen";
+   }
+   ```
+   
+  ![](Good.png)
+  ```java
+   ...
+   } catch (Exception e) {
+       throw new AssertionError("This exception should not happen");
+   }
+   ```
+
+  > Rationale: As the program flow has already triggered an exception, switching to assertions is not necessary when
+  > another exception can handle it just as well.
diff --git a/docs/CodingStandards.md b/docs/CodingStandards.md
index 7457e32..7d3a604 100644
--- a/docs/CodingStandards.md
+++ b/docs/CodingStandards.md
@@ -7,6 +7,7 @@ Note that some projects might have additional guidelines for the languages they
 * **GFMD** (GitHub Flavored Markdown): [Coding Standard](https://oss-generic.github.io/process/codingStandards/CodingStandard-Gfmd.html)
 * **HTML**: [Coding Standard](https://oss-generic.github.io/process/codingStandards/CodingStandard-Html.html)
 * **Java**: [Coding Standard](https://oss-generic.github.io/process/codingStandards/CodingStandard-Java.html)
+  | [Additional Guidelines](../codingStandards/AdditionalGuidelines-Java.md)
 * **JavaScript**: [Coding Standard](https://docs.google.com/document/d/1gZ6WG6HBTJYHAtVkz9kzi_SUuzfXqzO-SvFnLuag2xM/pub?embedded=true)
 * **JSP**: [Coding Standard](https://docs.google.com/document/d/14bXfdveXvoIaPBYpL19m4PK6oPabSnnoawj6OGjOzD4/pub?embedded=true)
 * JSTL