Entwickler-Coding-Richtlinien

Wenn du an der Entwicklung von WP STAGING mitwirken möchtest, mache dich bitte mit den folgenden Coding-Richtlinien und Best Practices vertraut.

Verwende PSR https://www.php-fig.org/psr/.
Verwende die kurze Array-Syntax [].
Verwende camelCase für Variablennamen.
Verwende StudlyCaps für Klassennamen.
Verwende Unterstriche in Datei- und Ordnernamen.
Vermeide Inline-Bedingungen.
Verwende Abkürzungen selten! Benutze keine Abkürzung, die nicht vom Team genehmigt wurde, und erfinde keine eigenen Abkürzungen, die nicht allgemein bekannt sind, wenn du Properties oder Methoden benennst.
Namen für Klassen, Methoden und Properties sollten ihren Zweck genau beschreiben.

Clean Code

Die Gesamtkosten für das Beibehalten von unordentlichem Code steigen im Laufe der Zeit.
Es ist sehr schwierig, ein Legacy-System von Grund auf neu aufzubauen. Refactoring und schrittweise Verbesserungen sind oft der bessere Weg.
In unordentlichen Codebasen kann es Tage oder Wochen dauern, Aufgaben zu erledigen, die nur Stunden dauern sollten.
Nimm dir die Zeit, um schnell zu sein.
Sauberer Code macht eine Sache gut. Schlechter Code versucht zu viel auf einmal.
Sauberer Code ist gut getestet.
Beim Lesen von gut geschriebenem Code tut jede Funktion ziemlich genau das, was du erwartest.
Wenn du mit einem Prinzip nicht einverstanden bist, das jemand mit jahrzehntelanger Erfahrung lehrt, solltest du zumindest deren Standpunkt in Betracht ziehen, bevor du ihn verwirfst.
Code wird viel häufiger gelesen als geschrieben.
Code, der leichter zu lesen ist, ist leichter zu ändern.
Hinterlasse die Codebasis besser, als du sie vorgefunden hast (Die Pfadfinder-Regel).

Kommentare und DocBlocks

Kommentare können lügen. Sie können von Anfang an falsch sein, oder sie können ursprünglich korrekt sein und dann mit der Zeit veralten, wenn sich der zugehörige Code ändert. Wenn du z. B. eine Methode umbenennst oder refaktorisierst, musst du immer prüfen, ob der Kommentar noch gültig ist.
Verwende Kommentare, um zu beschreiben, warum etwas so geschrieben ist, wie es ist, nicht um zu erklären, was passiert.
Kommentare können oft vermieden werden, indem du klar benannte Variablen verwendest und Codeabschnitte in klar benannte Funktionen extrahierst.
Versehe deine TODO-Kommentare mit einem einheitlichen Präfix, um die Suche zu erleichtern. Überprüfe und bereinige deine TODO-Kommentare regelmäßig.
Verwende DocBlocks nicht nur um ihrer selbst willen. Kommentare, die beschreiben, was eine Methode tut, welche Argumente sie entgegennimmt und was sie zurückgibt, sind oft bestenfalls redundant und schlimmstenfalls irreführend.
Kommentare sollten alle relevanten Informationen und den Kontext enthalten, die jemand beim Lesen des Kommentars benötigt. Sei nicht faul oder vage, wenn du einen Kommentar schreibst.
Journal-Kommentare und Datei-Autoren-Kommentare sind aufgrund von Versionskontrolle und Git Blame unnötig.
Kommentiere keinen toten Code aus. Lösche ihn einfach. Wenn du denkst, dass du den Code in Zukunft brauchst, dafür gibt es die Versionskontrolle.
Kommentiere so viel wie nötig, aber so wenig wie möglich. Wenn du deine Methode schreibst und den starken Drang verspürst, einen Kommentar dazu zu schreiben, ist meistens der Methodenname nicht klar genug oder der Code tut mehr als eine Sache. In diesem Fall solltest du ein Refactoring in Betracht ziehen, bevor du einen Kommentar schreibst.

Code Style

Binäre Operator-Abstände

Binäre Operatoren ‚=‘ und ‚=>‘ sollten von Leerzeichen umgeben sein. In den IDE-Code-Style-Einstellungen gibt es eine Autoformat-Option, mit der du die Zuweisungen von Schlüssel-Wert-Paaren so ausrichten kannst:

$array = [
    $var    => 'foo',
    $varvar => 'foo'
];

$var     = 1;
$var100  = 100;
$var2000 = 2000;

Dies ist ein praktischer Trick, um größere Abschnitte ähnlichen Codes lesbarer zu machen.

Yoda-Bedingungen

Wir haben abgestimmt, Yoda-Bedingungen zugunsten der Lesbarkeit nicht zu verwenden.

Nicht empfohlen:

if ( true === $var ) {}

Empfohlen:

if ( $var === true ) {}

Native Funktions-/Konstantenaufrufe

Native Invocation ist eine Technik, bei der ein führender Backslash () vor dem Funktions-/Konstantenaufruf hinzugefügt wird, um die Auflösung zu beschleunigen. So muss PHP nicht prüfen, ob die Funktion/Konstante aus dem Namespace oder nativ ist.

Wir haben abgestimmt, die Native-Invocation-Technik zugunsten der Lesbarkeit und zur Vermeidung von Fehleranfälligkeit in unserer Codebasis nicht zu verwenden.

In einigen Fällen ist es jedoch erlaubt, sie vorsichtig und mit Bedacht einzusetzen.

Nicht empfohlen:

if ( is_array($var) ) {}
if ( PHP_SAPI === 'cli') {}

Empfohlen:

if ( is_array($var) ) {}
if ( PHP_SAPI === 'cli') {}

Namespaces und Klassennamen

Gemäß den Prinzipien der objektorientierten Programmierung (OOP) sollten Klassennamen Substantive sein, da sie Objekte oder Konzepte im System darstellen. Dies hilft, den Code für andere Entwickler lesbarer und verständlicher zu machen.

Es ist jedoch erwähnenswert, dass einige Programmiersprachen, darunter PHP, die Verwendung von Verben als Klassennamen erlauben. In diesen Fällen wird das Verb in der Regel verwendet, um anzuzeigen, dass die Klasse eine Aktion oder ein Verhalten darstellt, anstatt eines Objekts.

Zum Beispiel könnte eine Klasse namens „Mailer“ ein Objekt darstellen, das E-Mails sendet, während eine Klasse namens „SendMail“ ein Verhalten darstellen könnte, das E-Mails sendet. Obwohl die Verwendung von Verben als Klassennamen technisch erlaubt ist, kann es den Code schwerer lesbar und verständlich machen und wird generell zugunsten von Substantiven nicht empfohlen.

Nur die Zeichen a-z, A-Z und 0-9 sind für Namespace- und Klassennamen erlaubt.
Namespaces werden normalerweise in UpperCamelCase geschrieben, aber Variationen sind für etablierte Namen und Abkürzungen erlaubt.
Klassennamen werden immer in UpperCamelCase geschrieben.
Der unqualifizierte Klassenname muss auch ohne den Namespace wörtlich gemeint sein.
Der Hauptzweck von Namespaces ist die Kategorisierung und Ordnung.
Klassennamen müssen Substantive sein, niemals Adjektive.
Der Name abstrakter Klassen muss mit dem Wort „Abstract“ beginnen, Klassennamen von Aspekten müssen mit dem Wort „Aspect“ enden.

Falsche Benennung von Namespaces und Klassen:

Vollqualifizierter Klassenname	Unqualifizierter Name	Bemerkungen
WPStagingFrameworkSessionPhp	Php	Die Klasse ist keine Darstellung von PHP
WPStagingFrameworkCacheBackendFile	File	Die Klasse repräsentiert keine Datei!
WPStagingFrameworkSessionInterface	Interface	Nicht erlaubt, „Interface“ ist ein reserviertes Schlüsselwort
WPStagingFrameworkControllerDefault	Default	Nicht erlaubt, „Default“ ist ein reserviertes Schlüsselwort
WPStagingFrameworkObjectsManager	Manager	Nur „Manager“ ist zu ungenau

Korrekte Benennung von Namespaces und Klassen:

Vollqualifizierter Klassenname	Unqualifizierter Name	Bemerkungen
WPStagingFrameworkUtilFileSystem	FileSystem	Das ist das FileSystem
WPStagingFrameworkCacheBackendFileBackend	FileBackend	Ein File Backend
WPStagingFrameworkSessionSessionInterface	SessionInterface	Interface für eine Session
WPStagingFrameworkStandardController	StandardController	Der Standard-Controller
WPStagingFrameworkObjectManager	ObjectManager

Grenzfälle bei der Benennung von Namespaces und Klassen:

Vollqualifizierter Klassenname	Unqualifizierter Name	Bemerkungen
WPStagingFrameworkMvcControllerInterface	ControllerInterface	Folglich gehört das Interface zu allen Controllern im Controller-Sub-Namespace
WPStagingFrameworkMvcControllerControllerInterface		Besser
WPStagingFrameworkCacheAbstractBackend	AbstractBackend	Dasselbe hier: In Wirklichkeit gehört diese Klasse zu den Backends
WPStagingFrameworkCacheBackendAbstractBackend		Besser

Methoden

Methodennamen sollten klar beschreiben, was sie tun, daher sollten sie mit einem Verb beginnen wie doSomething, makeSomething, isSomething, hasSomething.

Alle Methodennamen werden in lowerCamelCase geschrieben. Um Probleme mit verschiedenen Dateisystemen zu vermeiden, sind nur die Zeichen a-z, A-Z und 0-9 für Methodennamen erlaubt — verwende keine Sonderzeichen.

Mache Methodennamen beschreibend, aber halte sie gleichzeitig prägnant. Konstruktoren müssen immer __construct() heißen, verwende niemals den Klassennamen als Methodennamen.

myMethod()

someNiceMethodName()

betterWriteLongMethodNamesThanNamesNobodyUnderstands()

singYmcaLoudly()

__construct()

Properties & Variablen

Eine Variable sollte ein Substantiv oder Adjektiv sein und niemals ein Verb. Sie speichert etwas und sollte erklären, was sie enthält.

Verwende nicht das Schlüsselwort getSomething für eine Property. Das get ist für Getter und Setter reserviert und für Methoden, die explizit etwas tun und für die es kein besseres Schlüsselwort als get gibt.

Variablennamen werden in lowerCamelCase geschrieben und sollten:

Selbsterklärend sein.
Nicht bis zur Unkenntlichkeit abgekürzt werden, sondern lieber länger sein, wenn es ihre Bedeutung klarer macht.

Das folgende Beispiel zeigt zwei Variablen mit derselben Bedeutung, aber unterschiedlicher Benennung. Du wirst sicher zustimmen, dass die längeren Versionen besser sind (oder …?).

Gute Benennung von Variablen

$singletonObjectsRegistry

$argumentsArray

$aLotOfHtmlCode

renderHTMLtoScreen

Schlechte Benennung von Variablen

$sObjRgstry

$argArr

$cx

Als Sonderausnahme darfst du Variablennamen wie $i, $j und $k für numerische Indizes in For-Schleifen verwenden, wenn auf den ersten Blick klar ist, was sie bedeuten. Aber auch dann solltest du sie möglichst vermeiden.

i18n, sprintf(), esc_html_* und gettext()

Verwende immer zuerst gettext()-Funktionen und umschließe sie mit sprintf(), wenn es Parameter in einem übersetzbaren String gibt.

Falsch:

esc_html_e(sprintf('There are %1$d monkeys in the %2$s'), $number, $string), 'text-domain');

Richtig:

// Correct (multi-line):

sprintf(
	/* translators: number of monkeys, location. */
	__( 'There are %1$d monkeys in the %2$s', 'text-domain' ),
	(int) $number,
	esc_html( $string )
);

// Correct (single-line):

/* translators: number of monkeys, location. */
printf( __( 'There are %1$d monkeys in the %2$s', 'text-domain' ), intval( $number ), esc_html( $string ) );

Bei Verwendung von printf oder sprintf sind einfache Anführungszeichen (‚) um den String zwingend erforderlich, da doppelte Anführungszeichen („) PHP anweisen würden, $s als Variable s zu interpretieren, was nicht beabsichtigt ist.

Zur Standardisierung mit dem wporg-Übersetzungstool muss ein Übersetzer-Platzhalter enthalten sein.

/* translators: %s: name */
sprintf(esc_html__('string %s to translate', 'text-domain'), esc_html($string));

/* translators: %1$s = name1, %2$s = name2 */
sprintf(esc_html__('string %1$s to translate for %2$s', 'text-domain'), esc_html($string1), esc_html($string2));

Mehr dazu: https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#variables

If-Else-Bedingungen

Vermeide Inline-Bedingungen, wenn sie zusätzliche Klammern und If-Else-Anweisungen erfordern oder mehr als mehrere Zustände zu vergleichen haben.

Andernfalls ist es in Ordnung, sie inline oder in separaten Early-Return-Bedingungen zu schreiben.

Schlecht:

return ((!$this->isWindowsOs() && is_executable($fileName))) && is_writable($fileName) || ($this->isWindowsOs()) && is_writable($fileName);

Gut:

if (!$this->isWindowsOs && is_executeable && is_writeable()) {
     return true;
}

if ($this->isWindowsOs && is_writeable()) {
  return true;
}

return false;

Actions und Filter

Verwende eine Konstante, um den Filternamen zu deklarieren. Der Konstantenname sollte dem Muster FILTER_* entsprechen.
Beginne einen Filternamen immer mit wpstg, verwende Namespacing mit Punkten wie wpstg.backups.listing_table wobei listing_table der Methodenname ist, in dem die Action verwendet wird.

Zum Beispiel:

// Declare const for filter
const FILTER_CLONING_UPDATE_ACTIVE_PLUGINS_FILTER = 'wpstg.cloning.update.active_plugins'

und dann

apply_filters(self::CLONING_UPDATE_ACTIVE_PLUGINS_FILTER, $activePlugins);

Daten in wp_options speichern

Verwende eine Konstante, um den Optionsnamen zu deklarieren. Der Konstantenname sollte dem Muster OPTION_* entsprechen.
Beginne einen Tabellen-Optionsnamen immer mit wpstg, trenne Wörter mit Unterstrichen wie wpstg_backup_database_settings. Vergiss nicht, die neu hinzugefügte Option in die uninstall.php einzutragen.