Unsere Apex-Code-Convention
Dieses Dokument legt eine Reihe von Regeln und Stilen fest, die bei der Apex-Codierung in der Salesforce-Plattform zu befolgen sind. Die Einhaltung dieser Richtlinien kann die Lesbarkeit und Nachvollziehbarkeit des Quellcodes verbessern. Dies erleichtert die Wartung der Software.
Ziel
Die Einhaltung der folgenden Apex-Codierungs-Richtlinien in der Salesforce-Plattform gewährleistet
- konsistenten,
- leicht lesbaren und
- zuverlässigen Code,
insbesondere in großen Entwicklungsteams oder bei Projekten mit mehreren Mitwirkenden.
Anwendungsbereich
Eine Code-Convention ist ein fertiges Dokument, das eine umfassende Sammlung von Richtlinien enthält. Für die Erstellung einer eigenen Code-Convention können bereits bestehende Code-Conventions anderer Unternehmen herangezogen werden. Dabei können die Richtlinien aus dem Dokument vollständig oder leicht angepasst übernommen werden. Auf der Grundlage der Diskussionen und der Ergebnisse des 4-Augen-Prinzips können weitere Richtlinien in die Code Conventions aufgenommen werden, um zukünftige Unsicherheiten zu vermeiden.
Richtlinien
Durch die Analyse von 5 Kodierungskonventionen aus verschiedenen Unternehmen wurde unsere eigene Sammlung von Apex-Kodierungsrichtlinien in der Salesforce-Plattform abgeleitet. Dabei wurden nur die relevante Richtlinien berücksichtigt.
Benennungskonventionen
Im Trailhead (https://trailhead.salesforce.com/de/content/learn/modules/success-cloud-coding-conventions) werden häufig verwendete Namenskonventionen aufgeführt. Um diese Namenskonventionen zu identifizieren, hat sich Salesforce mit einigen der erfahrensten Success Cloud-Entwickler zusammengesetzt. Das Ergebnis ist die Tabelle „Success Cloud Naming Conventions“, die einen Überblick über die allgemein akzeptierten Konventionen für die gängigsten Salesforce Entitäten gibt.
Weitere Informationen zu den Namenskonventionen der Success Cloud finden Sie im Salesforce Quip-Dokument.
Aus dieser Namenskonventionstabelle übernehmen wir die folgenden Benennungsrichtlinien:
| Type | Naming Convention | Beschreibung | Beispiel |
| Apex Class | <Namespace>_<Class Name><Optional Suffix> |
|
SBCPT_CustomerAssessmentController
Account_SummarizeOpportunitiesExtension |
| Apex Test Class | <Class Being Tested>_Test | SBCPT_CustomerAssessmentController_Test
Account_SummarizeOpportunitiesExtensionTest |
|
| Apex Methods | <Verb(s)><(optional) Noun Set> | – Verben: beschreiben die durchgeführten Aktionen: get, save, check usw. – Substantivsatz: beschreibt, worauf die Verben wirken. |
getParentAccount() |
| Apex Variables | <Short yet meaningful nouns> | Vermeiden Sie Variablennamen mit nur einem Buchstaben, außer bei temporären Variablen oder Schleifenvariablen. | Good:
parentAccount Bad: pA pAcc |
| Apex Constants | <Capitalized words> | Sie sollten die Konstante beschreiben, ohne zu viele Worte zu verwenden. Alle Buchstaben müssen großgeschrieben werden. | MAX_CHARACTERS |
Funktionen
Funktionen sollten kurz und knapp sein und nur einem Zweck erfüllen. Sie sollten eine Sache tun und das gut.
Wenn Sie jedoch eine komplexe Funktion haben und den Verdacht haben, dass andere nicht verstehen, worum es bei der Funktion geht, dann sollten Sie die Obergrenzen umso mehr einhalten. Teilen Sie die Funktion in mehrere Hilfsfunktionen mit aussagekräftigen Namen auf.
Variablen Platzierung
Setzen Sie Deklarationen nur an den Anfang von Blöcken.
Versuchen Sie, lokale Variablen dort zu initialisieren, wo sie deklariert sind. Der einzige Grund, warum eine Variable nicht dort initialisiert werden sollte, wo sie deklariert wurde, ist, wenn der Anfangswert von einer zuvor durchgeführten Berechnung abhängt.
Beispiel:
| function z1(){//Good var a = 1; var b = 2; … } |
function z2(){//Bad … var a = 1; … var b = 2; … } |
Wahl des Klammerstils
Wir folgen dem Stil von Kernighan und Ritchie.
Beispiel:
| Kernighan and Ritchie style (Good):
functionTest(){ while (x == y) { function1(){ |
Allman style (Bad):
functionTest() while (x == y) function1() |
Verwendung von freiwilligen Klammern
Klammern werden für if-, else-, for-, do- und while-Anweisungen verwendet, auch wenn der Textkörper leer ist oder nur eine Anweisung enthält.
Beispiel:
| //Good
if(…){ |
//Bad
if(…) exampleFunction() |
Eine Anweisung pro Zeile
Nach jeder Anweisung folgt ein Zeilenumbruch.
Beispiel:
| //Good
function1(); |
//Bad
function1();function2(); |
Abstände
Um die meisten binären und ternären Operatoren, wie z.B. die folgenden, muss ein Leerzeichen gesetzt werden (auf jeder der beiden Seiten):
= + – < > * / % | & ^ <= >= == != ? :
Aber kein Leerzeichen nach dem Präfix Inkrement & Dekrement bei unären Operatoren:
++ —
Beispiel:
|
1.
Good:
spam(ham[1], {eggs: 2})
Bad:
spam( ham[ 1 ], { eggs: 2 } )
|
2. Good: x = 1 y = 2 Bad: x = 1 |
3. Good: i = i + 1 Bad: i=i+1 |
4. Good: if( x >= 35){ Bad: if( x>=35){ |
5. Casts should be followed by a blank Good: byte x = (byte) aNum; Bad: byte z = (byte)varExample; |
Wrapping-Linien
Passt ein Ausdruck nicht in eine Zeile, so ist er nach den folgenden allgemeinen Grundsätzen umzuwandeln:
- Umbruch nach einem Komma.
- Umbruch vor einem Operator.
- Umbrüche auf höherer Ebene sind Umbrüchen auf niedrigerer Ebene vorzuziehen.
- Richten Sie die neue Zeile am Anfang des Ausdrucks auf der gleichen Ebene wie die vorherige Zeile aus.
- Wenn die obigen Regeln zu einem unübersichtlichen oder am rechten Rand eingequetschten Code führen, können Sie stattdessen einfach 8 Leerzeichen einfügen.
Hinweis: Vermeiden Sie Zeilen mit mehr als 80 Zeichen, da sie schwer zu lesen sind. Im Allgemeinen sollten die Texte nicht länger als 70 Zeichen sein.
Hier sind einige Beispiele für Methodenaufrufe:
var a = function(longExpression1, longExpression2,
longExpression3, longExpression4, longExpression5);
var b = function1(longExpression1,
function2(longExpression2, longExpression3) );
var c = long_function_name( var_one, var_two,
var_three, var_four)
var b = very_vrylong_function_name(
var_one, var_two, var_three,
var_four){
…
}
Nachfolgend ein Beispiel für den Bruch eines arithmetischen Ausdrucks. Es ist vorzuziehen, da der Bruch außerhalb des geklammerten Ausdrucks erfolgt, der sich auf einer höheren Ebene befindet.
longName1 = longName2 * (longName3 + longName4 – longName5)
+ 4 * longname6;
Der Zeilenumbruch für if-Anweisungen sollte im Allgemeinen die 8-Leerzeichen-Regel verwenden, da die herkömmliche Einrückung (4 Leerzeichen) die Sichtbarkeit des Textkörpers erschwert. Zum Beispiel:
| //DON’T USE THIS INDENTATION
if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //BAD WRAPS doSomethingAboutIt();//MAKES THIS LINE EASY TO MISS } |
//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } |
Special characters
Für jedes Zeichen, das eine spezielle Escape-Sequenz hat (\b, \t, \n, \f, \r, \", \' and \\), wird diese Sequenz anstelle der entsprechenden oktalen (e.g. \012) oder Unicode-Escape-Sequenz (e.g. \u000a) verwendet.
Beispiel:
| Good:
„Hallo Mr. \“Anton\““ => Hallo „Anton“ |
Bad:
„Hallo Mr. \u0022Anton\u0022“ => Hallo „Anton“ |
Für die übrigen Nicht-ASCII-Zeichen wird entweder das eigentliche Unicode-Zeichen (z. B. ∞) oder das entsprechende Unicode-Escape (z. B. \u221e) verwendet. Die Wahl hängt nur davon ab, was den Code leichter lesbar und verständlich macht.
Beispiel:
Beispiele, bei denen die beste Variante die erste ist:
String firstExample = „μs“;
String secondExample = „\u03bcs“; // „μs“
String thirdExample = „\u03bcs“; // Greek letter mu, „s“
Kommentare
Kommentare sind gut, aber es besteht auch die Gefahr, zu viel zu kommentieren. Versuchen Sie NIEMALS in einem Kommentar zu erklären, WIE Ihr Code funktioniert: Es ist viel besser, den Code so zu schreiben, dass die Funktionsweise offensichtlich ist, und es ist Zeitverschwendung, schlecht geschriebenen Code zu erklären.
Diskussionen über nicht-triviale oder nicht offensichtliche Design-Entscheidungen sind angemessen, aber vermeiden Sie es, Informationen zu wiederholen, die bereits im Code vorhanden (und aus dem Code ersichtlich) sind. Redundante Kommentare können leicht veralten. Im Allgemeinen sollten Sie Kommentare vermeiden, die während der Entwicklung des Codes veraltet sein könnten.
Im Allgemeinen sollten Ihre Kommentare beschreiben, WAS Ihr Code tut, nicht WIE. Versuchen Sie auch, Kommentare innerhalb eines Funktionskörpers zu vermeiden: wenn die Funktion so komplex ist, dass Sie Teile davon separat kommentieren müssen. Sie können kleine Kommentare einfügen, um auf etwas besonders Kluges (oder Hässliches) hinzuweisen oder zu warnen. Stattdessen sollten Sie die Kommentare an den Anfang der Funktion setzen und erklären, was sie tut und eventuell WARUM sie es tut. Weitere Informationen finden Sie in den Beispielen in der Regel „JavaDoc Kommentarblöcke“.
Hinweis: Die Häufigkeit von Kommentaren spiegelt manchmal eine schlechte Qualität des Codes wider. Wenn Sie sich gezwungen fühlen, einen Kommentar hinzuzufügen, sollten Sie den Code umschreiben, um ihn klarer zu machen.
