Merge branch 'gcg18000'

Author: ManticSic

coding-guidelines/docs/guidelines/general/18000.de.md

@@ -0,0 +1,114 @@
+# Exceptions und Prozessbeendigung
+
+## Verwende keine Exceptions statt `if...else`-Statements (GCG18001) <img src="/img/2.png" alt="recommendation level 2" />
+Exceptions sollten nicht verwendet werden, um Entscheidungen zu treffen, sondern
+um Fehler entsprechend ihrer Ursache und möglichen Auswirkungen zu behandeln.
+
+Diese Regel kombiniert u. A. die Regeln `GCG18002` und `CGC18003`.
+
+## Werf keine Exceptions die direkt wieder gefangen werden (GCG18002) <img src="/img/1.png" alt="recommendation level 1" />
+```
+// not okay!
+class Foo {
+    public void AnyMethod() {
+        try {
+            throw new Exceptions();
+        } catch {
+            // do something
+        }
+    }
+}
+
+// also not okay
+class Foo {
+    public void AnyMethod() {
+        try {
+            MethodThrowingException();
+        } catch {
+            // do something
+        }
+    }
+    
+    private void MethodThrowingException() {
+        throw new Exception();
+    }
+}
+
+// maybe okay
+class Foo {
+    public void AnyMethod() {
+        try {
+            MethodThrowingException();
+        } catch {
+            // do something
+        }
+    }
+    
+    public void MethodThrowingException() {
+        throw new Exception();
+    }
+}
+
+// okay!
+class Foo {
+    public void AnyMethod() {
+        try {
+            new Bar().MethodThrowingException();
+        } catch {
+            // do something
+        }
+    }
+}
+
+class Bar {
+    public void MethodThrowingException() {
+        throw new Exception();
+    }
+}
+```
+
+## Statt NullPointer-Exceptions zu fangen, prüfe sie vorzeitig ab  (GCG18003) <img src="/img/1.png" alt="recommendation level 1" />
+NullPointer-Exceptions entstehen, wenn ein Objekt einen nicht erwarteten Zustand
+hat. Statt im Prozess solche Exceptions abzufangen, sollten sie früh erkannt und
+entsprechend behandelt werden.
+
+## Werf eine Exception, statt eine Art von Status-Code zurückzugeben (GCG18004) <img src="/img/2.png" alt="recommendation level 2" />
+Eine Codebasis die Rückgabewerte verwendet um einen Status (erfolgreich oder
+fehlgeschlagen) zu kommunizieren, tendiert dazu, viele verschachtelte
+`if`-Statements überall verteilt zu haben. Oft wird auch vergessen, den
+Rückgabewert ordentlich zu prüfen.  
+Geworfene Exceptions können abgefangen oder durch eine genauere Exception
+ersetzt werden, um sie an auf einer höheren Ebene zu behandeln. In den meisten
+Systemen ist es normal, dass Exceptions immer dann geworfen werden, wenn eine
+unerwartete Situation auftaucht.
+
+## Werf eine möglichst genaue Exception (GCG18005) <img src="/img/2.png" alt="recommendation level 2" />
+Wenn es möglich ist, eine Exception von einem spezifischen Typ zu werfen,
+dann sollte ein Typ gewählt werden, der bereits ohne zusätzliche Message
+genau aussagt, was passiert ist.
+
+## Nutze aussagekräftige Exception-Messages (GCG18006) <img src="/img/2.png" alt="recommendation level 2" />
+Die Exceptions-Message sollte den Grund für die Exception erklären und eindeutig
+beschreiben was getan werden muss, um die Exception zu vermeiden.
+
+## Vermeide das Verbergen von Fehlern durch das Abfangen von generischen Exceptions (GCG18007) <img src="/img/1.png" alt="recommendation level 1" />
+Vermeide das Abfangen von nicht spezifischen Exceptions, wie z. B. `Exception`,
+`SystemException` etc. Nur auf der höchsten Ebene, als letzte Chance eine
+Exception abzufangen, sollten nicht spezifische Exceptions behandelt werden,
+um einen graceful Shutdown zu ermöglichen.
+
+## Richtige Verwendung und Dokumentation von Exit-Codes (GCG18008) <img src="/img/1.png" alt="recommendation level 1" />
+Es sollte immer sichergestellt werden, dass beim Beenden der Applikation ein
+zutreffender Exit-Code ausgegeben wird. Dadurch ist es anderen Systemen möglich
+auf das Beenden der Anwendung zu reagieren, außerdem können Benutzer
+nachvollziehen wie und warum eine Anwendung beendet wurde.
+
+Es hat sich etabliert, dass der Exit-Code `0` für ein erwartetes und
+erfolgreiches Beenden steht, hingegen alle abweichenden einen Fehler oder
+eine unerwartete Situation repräsentieren.
+
+Alle Exit Codes müssen dokumentiert werden!
+
+## Logging bei gezwungener Beendigung (GCG18009) <img src="/img/1.png" alt="recommendation level 1" />
+Wenn die Anwendung unerwartet beendet wird, sollte der Grund mit dem
+höchsten Log-Level dokumentiert werden.

coding-guidelines/docs/guidelines/general/18000.md

@@ -0,0 +1,109 @@
+# Exceptions and Process Termination
+
+## Don't use exceptions instead of `if...else` statements (GCG18001) <img src="/img/2.png" alt="recommendation level 2" />
+Exceptions shouldn't be used to make decisions, but to handle errors depending
+on their reason and impact.
+
+This rule combines among others the rules `GCG18002` and `GCG18003`.
+
+## Don't throw exceptions and catch them at the same time (GCG18002) <img src="/img/1.png" alt="recommendation level 1" />
+```
+// not okay!
+class Foo {
+    public void AnyMethod() {
+        try {
+            throw new Exceptions();
+        } catch {
+            // do something
+        }
+    }
+}
+
+// also not okay
+class Foo {
+    public void AnyMethod() {
+        try {
+            MethodThrowingException();
+        } catch {
+            // do something
+        }
+    }
+    
+    private void MethodThrowingException() {
+        throw new Exception();
+    }
+}
+
+// maybe okay
+class Foo {
+    public void AnyMethod() {
+        try {
+            MethodThrowingException();
+        } catch {
+            // do something
+        }
+    }
+    
+    public void MethodThrowingException() {
+        throw new Exception();
+    }
+}
+
+// okay!
+class Foo {
+    public void AnyMethod() {
+        try {
+            new Bar().MethodThrowingException();
+        } catch {
+            // do something
+        }
+    }
+}
+
+class Bar {
+    public void MethodThrowingException() {
+        throw new Exception();
+    }
+}
+```
+
+## Instead of catching null pointer exceptions, introduce null validations (GCG18003) <img src="/img/1.png" alt="recommendation level 1" />
+Null pointer exceptions arise when an object has an unexpected state. Instead of
+catching this kind of exceptions, you should validate the objects state. 
+
+## Throw exceptions rather than returning some kind of status value (GCG18004) <img src="/img/2.png" alt="recommendation level 2" />
+A code base that uses return values to report success or failure tends to have
+nested if-statements sprinkled all over the code. Quite often, a caller forgets
+to check the return value anyway.  
+Structured exception has been introduced to allow you to throw exceptions and
+catch or replace them at a higher layer. In most systems it is quire common to
+throw exceptions whenever an unexpected situations occurs.
+
+## Throw the most specific exception that is appropriate (GCG18005) <img src="/img/2.png" alt="recommendation level 2" />
+If it's possible to throw exceptions of a specific type, then you should that
+the most specific one, which don't need a message, to understand what happen.
+
+## Provide a rich and meaningful exception message text (GCG18006) <img src="/img/2.png" alt="recommendation level 2" />
+The message should explain the cause of the exception, and clearly describe what
+needs to be done to avoid the exception.
+
+## Don't swallow errors by catching generic exceptions (GCG18007) <img src="/img/1.png" alt="recommendation level 1" />
+Avoid swallowing errors by catching non-specific exceptions, such as
+`Exception`, `SystemException`, and so on, in application code. Only in
+top-level code, such as a last chance exception handler, you should catch a
+non-specific exception for logging purposes and a graceful shutdown of the
+application.
+
+## Right usage and documentation of exit codes (GCG18008) <img src="/img/1.png" alt="recommendation level 1" />
+The application should always send a proper exit code, when the application
+was shutting down. So other applications can handle the termination of the
+process and users can understand why and how an application was stopped.
+
+Exit code `0` means that the application was successfully stopped without any
+error. All other codes representing an unexpected situation.
+
+All exit code must be documented!
+
+## Logging in case of unexpected shutdown (GCG18009) <img src="/img/1.png" alt="recommendation level 1" />
+If the application stops unexpected, the reason should be logged in the
+highest possible log level.

coding-guidelines/mkdocs.yml

@@ -26,6 +26,7 @@ nav:
           - Maintainability: guidelines/general/15000.md
           - Documentation: guidelines/general/16000.md
           - Logging: guidelines/general/17000.md
+          - Exceptions and Process Termination: guidelines/general/18000.md
 
 plugins:
   - search: { }
@@ -41,3 +42,4 @@ plugins:
           Tools and Automation: Tools und Automatisierung
           Namming Conventions: Namenskonvention
           Documentation: Dokumentation
+          Exceptions and Process Termination: Exceptions und Prozessbeendigung