Merge pull request #12 from ManticSic/translate_gcg14000

Translate GCG14000

Author: ManticSic

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

@@ -1,87 +1,81 @@
-**en Translation coming soon**
-
-# Namenskonvention
-
-## Verwende US English (GCG14001) <img src="/img/1.png" alt="recommendation level 1" />
-Alle Identifier (Typen, Member, Parameter, Variablen etc.) sollte mit Wörtern aus
-dem amerikanischen Englisch gebildet werden.
-
-- Die Namen sollten leicht lesbar und grammatikalisch richtig sein.  
-  Beispiel: `HorizontalAlginment` ist besser als `AlignmentHorizontal`
-- Lesbarkeit ist wichtiger als Kürze.  
-  Beispiel: `CanScrollHorizontally` ist besser als `ScrollableX`
-- Bei den Namen sollte auf Schlüsselwörter aus den verbreiteten
-  Programmiersprachen verzichtet werden.
-
-## Verwende die richtige Schreibweise für Sprachelemente (GCG14002) <img src="/img/1.png" alt="recommendation level 1" />
-Abhängig von der jeweiligen Sprache sollte die richtige Schreibweise für
-Sprachelemente wie z. B. Klassen, Methoden und Variablen gewählt werden.
-Die am meisten verbreiteten sind
-[Camel Case, Pascal Case, Snake Case und Kebab Case][letter-case].
-
-## Verwende keine Zahlen in Variablen, Parametern und anderen Member (GCG14003) <img src="/img/2.png" alt="recommendation level 2" />
-Solche Namen resultieren meisten aus Faulheit. Entweder weil man sich nicht
-genug Gedanken über einen passenden Namen gemacht hat, oder man mehrere
-Elemente, statt einer Liste implementiert hat.
-
-## Verwende keine Präfixe (GCG14004) <img src="/img/2.png" alt="recommendation level 2" />
-Typen, Member, Parameter, Variablen etc. sollten nicht mit einem Präfix versehen
-werden, um ihren Typ oder Scope zu definieren. Bekannt sind z. B. die Präfixe
-`g_` für `global`, `s_` für `static` oder `string`, `i_` für `înteger` und `_`
-für private Member.
-
-Nicht in allen Sprachen ist es möglich, diese Regel umzusetzen. In einigen
-Sprachen werden Backingfields mit dem Präfix `_` versehen. In andere Sprachen
-ist dieses Präfix für private oder spezielle Member nötig.
-
-## Verwende keine Abkürzungen (GCG14005) <img src="/img/2.png" alt="recommendation level 2" />
-Abkürzungen wie `btn` für `Button` und `cmd` für `Command` tragen nicht zur
-Lesbarkeit und Verständlichkeit bei und sollten daher nicht genutzt. Ebenfalls
-sollten Namen vermieden werden, die nur aus einem Buchstaben bestehen, z. B.
-`i` für `index` und `q` für `query`.
-
-**Ausnahme: ** es sollten nur Abkürzungen genutzt werden, die allgemein oder in
-der jeweiligen Domäne geläufig sind.
-
-## Benenne Member, Parameter und Variablen entsprechend ihrer Bedeutung, nicht ihres Typen (GCG14006) <img src="/img/2.png" alt="recommendation level 2" />
-Der Name sollte die Funktion wiederspiegeln und nicht den dahinter stehenden
-Typen.
-
-Namen für Listen und Maps sollten den Plural verwenden.
-
-## Nutze bei der Benennung von Typen Substantive, Substantiv-Phrasen oder Adjektiv-Phrasen (GCG14007) <img src="/img/2.png" alt="recommendation level 2" />
-Benennung|Beispiel
+# Naming convention
+
+## Use US English (GCG14001) <img src="/img/1.png" alt="recommendation level 1" />
+All identifiers (Types, member, parameters, variables etc.) should be named
+using words from the US English language.
+
+- Names should be easily readble, preferably grammatically correct names.  
+  Example: `HorizontalAlginment` is better than `AlignmentHorizontal`.
+- Favor readability over brevity.  
+  Example: `CanScrollHorizontally` is better than `CanScrollHorizontally`.
+- Avoid using names that conflicts with keywords from widely spread used
+  programming languages.
+
+## Use proper notation for language elements (GCG14002) <img src="/img/1.png" alt="recommendation level 1" />
+Depanding on the used programming language the proper notation for language
+elements such as classes, method and variables should be used. Widely spread
+casings are [camel case, pascal case, snake case and kebab case][letter-case].
+
+
+## Don't include numbers in varfianles, parameters and type members (GCG14003) <img src="/img/2.png" alt="recommendation level 2" />
+In most cases these kind of names are lazy excuses for not defining a clear and
+intention-revealing name. Often they are used instead of collections.
+
+## Don't use prefixes (GCG14004) <img src="/img/2.png" alt="recommendation level 2" />
+Types, type members, parameters, variables etc. shouldn't include a prefix to
+define the scope or type. Known prefixes are `g_` for `global`, `s_` for
+`static` or `string`, `i_` for `integer` and `_` for private members.
+
+In some programming languages it is not possible to obey this rule. Many
+languages uses `_` for backing fields, other to communicate that a member is
+private.
+
+## Don't use abbreviations (GCG14005) <img src="/img/2.png" alt="recommendation level 2" />
+Abbreviations like `btn` for `button` and `cmd` for `command` harm the
+readability and intelligibility. Avoid single character variable names, such as
+`i` or `q`. Use `index` or `query`.
+
+**Exception: ** Use well-known acronyms and abbreviations that are widely
+accepted or well-known in your work domain. For instance, use acronym `UI`
+instead of `UserInterface` and abbreviation `Id` instead of `Identity`.
+
+## Name members, parameters and variables according to their meaning and not their type (GCG14006) <img src="/img/2.png" alt="recommendation level 2" />
+The name should describe the functionality and not their type.
+
+Identifiers  that refer to a collection type should have plural names.
+
+## Name types using nouns, noun phrases or adjective phrases (GCG14007) <img src="/img/2.png" alt="recommendation level 2" />
+Naming|Example
 :--|:---
-Substantiv|`IComponent`
-Substantiv-Phrase|`ICustomAttributeProvider`
-Adjektiv-Phrase|`IPersistable`
+noun|`IComponent`
+noun phrase|`ICustomAttributeProvider`
+adjective phrase|`IPersistable`
 
-## Nutze bei der Benennung von Methoden Verben oder Verb-Objekt-Paare (GCG14008) <img src="/img/2.png" alt="recommendation level 2" />
-Benennung|Beispiel
+## Name methods using verbs or verb-object pairs (GCG14008) <img src="/img/2.png" alt="recommendation level 2" />
+Naming|Example
 :--|:---
-Verb|`Show`
-Verb-Objekt-Paar|`ShowDialog`
+verb|`Show`
+verb-object pair|`ShowDialog`
 
-Die Namen sollten ein Hinweis darauf sein, was die Methode macht.
+The name should describe the *what*, and if possible, the *why*.
 
-## Wähle bei der Benennung von generischen Parametern aussagekräftige Namen (GCG14009) <img src="/img/2.png" alt="recommendation level 2" />
-Präfixe generische Parameter mit dem Buchstaben `T` für `Type`.
+## Name generic type parameters with descriptive names (GCG14009) <img src="/img/2.png" alt="recommendation level 2" />
+Always prefix type parameters with the letter `T` for `Type`.
 
-Verwende einen Namen, der die Bedeutung des übergebenen Typen erklärt.
+The name should describe the *what*.
 
-## Wähle Namen entsprechend anderer Member innerhalb der jeweiligen Sprache oder des jeweiligen Frameworks (GCG14010) <img src="/img/1.png" alt="recommendation level 1" />
-Um einen Entwickler, der bereits mit einer Sprache oder einem Framework vertraut
-ist, den Einstieg in ein Projekt möglichst leicht zu machen, sollte Namen
-verwendet werden, die in der jeweiligen Sprache bzw. dem jeweiligen Framework
-verwendet werden.
+## Name members similarly to other members in the used programming language or framework (GCG14010) <img src="/img/1.png" alt="recommendation level 1" />
+To let developers, who are already familiar with the used programming
+language or framework, finding their way into your project, you should use a
+naming pattern which is widely used by the language or framework.
 
-## Vermeide Namen, die verwechselt werden können (GCG14011) <img src="/img/1.png" alt="recommendation level 1" />
-Nur weil ein Ausdruck technisch korrekt ist, muss er nicht verständlich sein.
+## Avoid short names or names that can be mistaken for other names (GCG14011) <img src="/img/1.png" alt="recommendation level 1" />
+Although technically correct, statements like the following can be confusing:
 ```
 bool b001 = (lo == l0) ? (I1 == 11) : (lOl != 101);
 ```
 
-## Wiederhole nicht den Namen eines Typen innerhalb seiner Member (GCG14013) <img src="/img/1.png" alt="recommendation level 1" />
+## Don't repeat the name of a class or enumeration in its members (GCG14013) <img src="/img/1.png" alt="recommendation level 1" />
 ```
 class Employee
 {
@@ -99,19 +93,18 @@ class Employee
 }
 ```
 
-## Vermeide Klassennamen die Wörter wie Utility oder Helper beinhalten (GCG14013) <img src="/img/2.png" alt="recommendation level 2" />
-Klassen, die Wörter wie `Utility` oder `Helper` in dem Namen haben, sind meist
-statisch und entstehen durch Missachten von den Regeln der objektorientierten
-Programmierung.
+## Avoid class containing terms like `Utility` and `Helper` (GCG14013) <img src="/img/2.png" alt="recommendation level 2" />
+Class containing terms like `Utility` or `Helper` are usually static classes and
+are introduced without considering object-oriented principles. 
 
-## Vermeide Methodennamen das Wort And beinhalten (GCG14014) <img src="/img/2.png" alt="recommendation level 2" />
-Methoden, die das Wort `And` beinhalten, machen meist mehr als eine Sache und
-verstoßen damit gegen das [Single Responsibility Principle][srp].
+## Avoid method names containing the word `and` (GCG14014) <img src="/img/2.png" alt="recommendation level 2" />
+A methods containing the word `and` implies, that it is doing more than one
+thing, which violates the [Single Responsibility Principle][srp].
 
 ## Präfixen von booleschen Variablen und Member (GCG14015) <img src="/img/2.png" alt="recommendation level 2" />
-Um die Aussagekraft von booleschen Variablen oder Member zu erhöhen, sollten
-diese mit den Worten `is`, `has`, `can`, `allows` oder `supports` versehen
-werden.
+## Prefixing of boolean variables and members (GCG14015) <img src="/img/2.png" alt="recommendation level 2" />
+To make boolean variables and members more descriptive consider prefixing them
+with `Is`, `Has`, `Can`, `Allows` or `Supports`.
 
 [letter-case]: https://en.wikipedia.org/wiki/Letter_case#Special_case_styles
 [srp]: https://en.wikipedia.org/wiki/Single-responsibility_principle