Merge pull request #9 from ManticSic/translate_cgc16000

Translate GCG16000

Author: ManticSic

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

@@ -1,44 +1,39 @@
-**en Translation coming soon**
+# Documentation
 
-# Dokumentation
+## Write comments in US English (CGC16001) <img src="/img/1.png" alt="recommendation level 1" />
 
-## Verwende US Englisch für Kommentare (CGC16001) <img src="/img/1.png" alt="recommendation level 1" />
-
-## Verwende US Englisch für Dokumentation (CGC16002) <img src="/img/1.png" alt="recommendation level 1" />
+## Write code documentation in US English (CGC16002) <img src="/img/1.png" alt="recommendation level 1" />
 
 ## Dokumentiere alle von außerhalb verfügbaren Typen und Members (CGC16003) <img src="/img/2.png" alt="recommendation level 2" />
-Alle Typen und Members, die von außerhalb des Programmes, aber auch außerhalb
-Namespaces, Paketen oder Typen innerhalb des Programmes erreichbar sind, sollten
-mit, für die jeweilige Sprache standardisierte Style, dokumentiert werden. Auf
-diesen Weg können andere Entwickler den Verwendungszweck und die Verwendung
-verstehen, ohne den eigentlichen Code zu kennen.
-
-Außerdem ist es möglich, mit entsprechenden Tools, eine professionell aussehende
-Dokumentation zu erstellen.
-
-## Schreibe Dokumentation für andere (CGC16004) <img src="/img/2.png" alt="recommendation level 2" />
-Dokumentation sollte für Nutzer geschrieben werden, die den dahinterstehenden
-Code nicht kennen. Sowohl der Verwendungszweck als auch die Verwendung sollte
-klar erklärt werden, um die bestmögliche Verwendung sicherzustellen.
-
-## Vermeide Inline-Kommentare (CGC16005) <img src="/img/2.png" alt="recommendation level 2" />
-Wenn Inline-Kommentare nötig sind, sollte es in betracht gezogen werden, ob
-es besser wäre, den betroffenen Code in eine eigene Methode mit einem
-aussagekräftigen Namen auszulagern.
-
-## Verwende keine Kommentare, um zukünftige Aufgaben festzuhalten (CGC16006) <img src="/img/2.png" alt="recommendation level 2" />
-Es ist gut, wenn Arbeit, die aktuell nicht erledigt werden konnte, festzuhalten,
-allerdings sollte dies in einem Projektmanagementsystem erfolgen. Die Verwendung
-von `TODO`-Kommentare ist zwar auch eine Möglichkeit, allerdings wird in der
-Praxis nicht oder nur selten nach solchen Kommentaren gesucht und gelöst.
-
-Eine weitere Möglichkeit ist eine Kombination aus beiden. Ein Ticket in dem
-jeweiligen Projektmanagementsystem anlegen und ein dazugehöriges
-`TODO`-Kommentar anlegen und in diesem das Ticket referenzieren.
-
-## Schreib Kommentare um komplexe Algorithmen oder Entscheidungen zu erklären (CGC16007) <img src="/img/1.png" alt="recommendation level 1" />
-Kommentare sollten sich auf das `Was?` und `Warum?` konzentrieren, statt auf dem
-`Wie?`. Die Statements sollten nicht Zeile für Zeile erklärt werden, sondern es
-sollte das Ziel erklärt werden, und weshalb genau diese Lösung verwendet wurde,
-wenn sie einer offensichtlicheren vorgezogen wurde, z. B. welche Probleme
-dadurch vermieden werden.
+Documenting all types and members, which are accessible from outside (assembly,
+namespace, class, …). Use the common way to document that kind of code,
+depending on your programming language (javadoc for java, XMLDoc for .Net and so
+on). This way other developers can get the most out of your function without
+knowing the concrete implementation.
+
+Furthermore, you can use tools to create professionally looking documentation.
+
+## Write documentation with other in mind (CGC16004) <img src="/img/2.png" alt="recommendation level 2" />
+Write the documentation with other in mind. Assume they will not have access to
+the full source, the requirements and specifications, so try to explain how to
+get the most of the functionality of your code.
+
+## Avoid inline comments (CGC16005) <img src="/img/2.png" alt="recommendation level 2" />
+If you feel the need to explain a block of code using a comment, consider
+replacing that block with a method with a clear name.
+
+## Don't use comments for tracking work to be done later (CGC16006) <img src="/img/2.png" alt="recommendation level 2" />
+Annotating a block of code or some work to be done using a `TODO` or similar
+comment may seem a reasonable way of tracking work-to-be-done. In reality,
+nobody really searches for comments like that. Use a project management system
+to keep track of leftovers.
+
+Another way is a combination of the usage of a work item in a project management
+system, and a related `TODO` comment, with a reference to that work item.
+
+## Only write comments to explain complex algorithms or decisions (CGC16007) <img src="/img/1.png" alt="recommendation level 1" />
+Try to focus comments on the *why* and *what* of a code block and not the *how*.
+Avoid explaining the statements in words, but instead help the reader understand
+why you chose a certain solution or algorithm and what you are trying to
+achieve. If applicable, also mention that you chose an alternative solution
+because you ran into a problem with the obvious solution.