In der Informatik gibt es nur zwei schwierige Dinge: die Ungültigmachung des Caches
und Dinge benennen.
- Phil Karlton
Wir Entwickler verbringen mehr Zeit damit, Code zu lesen als ihn zu schreiben. Es ist wichtig, dass der Code lesbar und klar über seine Absicht ist.
Im Folgenden finden Sie einige Ratschläge, die auf meiner Erfahrung mit der Benennung von Dingen basieren.
Bedeutung
Ein Name, sei es eine Variable, eine Eigenschaft, eine Klasse oder eine Schnittstelle, sollte den Zweck widerspiegeln, warum er eingeführt wird und wie er verwendet wird.
Verwenden Sie genaue Namen
Wenn man sich ohne zusätzliche Kommentare keine Vorstellung von Verwendung und Zweck machen kann, ist der Name nicht gut genug. Wenn eine sofortige Verwendung oder eine auf der Benennung basierende Zweckidee falsch ist, ist die Benennung nicht akzeptabel.
Die schlechteste Benennung ist, wenn ein Methodenname derjenige ist, der ihn liest.
Vermeiden Sie bedeutungslose Namen
Dies sind Namen wie $i , $j , $k usw. Während diese in Zyklen verwendet werden können, verschwenden sie in anderen Fällen die Lesbarkeit.
Eine häufige Quelle für solche Namen ist die klassische Wissenschaft, bei der die meisten Formeln Ein-Buchstaben-Variablen verwenden, um schneller schreiben zu können. Infolgedessen können Sie diese Formeln ohne einen einleitenden Absatz, in dem die Benennung erläutert wird, nicht verstehen. Oft ist dieser Absatz schwer zu finden.
Da der Informatikunterricht eine bedeutende Anzahl klassischer naturwissenschaftlicher Disziplinen umfasst, gewöhnen sich die Schüler an eine solche Benennung und bringen sie in die Programmierung ein.
Benennen von Klassen, Schnittstellen, Eigenschaften und Methoden
Der Klassenname sollte ein oder mehrere Substantive sein. Es sollte keine Verben geben. Vermeiden Sie "Daten", "Manager", "Info", "Prozessor", "Handler", "Hersteller", "Util" usw. da diese normalerweise ein Indikator für vage Namen sind.
Schnittstellen sind normalerweise entweder Substantive oder Adjektive. Einige Teams, einschließlich PHP-FIG , haben sich dafür entschieden, Schnittstellen mit Interface zu fixieren. Einige machen es mit dem Präfix I und andere verwenden kein Präfix oder Postfix. Ich finde all dies akzeptabel, falls Sie konsequent sind.
Eigenschaften sollten mit Substantiven oder Adjektiven benannt werden. Verwenden Sie für Boolesche Werte positive Phrasen, denen gegebenenfalls "Is", "Can" oder "Has" vorangestellt sind.
Methodennamen sollten ein oder mehrere Verben enthalten, da es sich um Aktionen handelt. Wählen Sie ein Verb, das beschreibt, was die Methode tut, nicht wie sie es tut.
Obwohl dies nicht unbedingt erforderlich ist, empfiehlt es sich, den abgeleiteten Klassennamen mit dem Namen der Basisklasse zu beenden:
class Exception {} class InvalidArgumentException extends Exception {}
Konsistenz
Verwenden Sie einen einzelnen Namen für ein einzelnes Konzept. Seien Sie konsequent.
Ein gutes Beispiel ist die Verwendung von begin / end überall, anstatt es mit start / finish mischen.
Befolgen Sie die Konventionen für den Codestil
Bei der Entwicklung eines Projekts muss sich ein Team auf den Codestil und die von ihm verwendeten Namenskonventionen einigen und diese befolgen. Wenn ein Teil der Konventionen von einigen Teammitgliedern nicht akzeptiert wird, sollte er überprüft, geändert und eine neue Regel festgelegt werden.
Für PHP ist PSR-2 derzeit die häufigste Konvention, und die meisten internen Projektkonventionen basieren darauf.
Ausführlichkeit
Vermeiden Sie die Wiederverwendung von Namen
Die Verwendung des gleichen Namens für viele Konzepte sollte nach Möglichkeit vermieden werden, da dies zwei Probleme mit sich bringt:
- Beim Lesen muss der Kontext berücksichtigt werden. Normalerweise bedeutet dies, ständig zum Namespace oder zur Paketdeklaration zu gelangen.
- Nach solchen Namen zu suchen ist ein Schmerz.
Kontraktionen vermeiden
Verwenden Sie keine Kontraktionen. Häufige Beispiele sind:
function cntBigWrds($data, $length) { $i = 0; foreach ($data as $iter) { if (mb_strlen($iter) > $length) { $i++; } } return $i; } $data = ['I', 'am', 'word']; echo cntBigWrds($data, 3);
Der obige Code lautet bei richtiger Benennung:
function countWordsLongerThan(array $words, int $minimumLength) { $count = 0; foreach ($words as $word) { if (mb_strlen($word) > $minimumLength) { $count++; } } return $count; } $words = ['I', 'am', 'word']; echo countWordsLongerThan($words, 3);
Beachten Sie dennoch, dass kurze erklärende Namen ohne Kontraktionen besser sind als lange erklärende Namen. Nehmen Sie die Ausführlichkeit also nicht zu extrem, wenn Sie Namen wie processTextReplacingMoreThanASingleSpaceWithASingleSpace() .
Wenn der Name zu lang ist, bedeutet dies entweder, dass er umformuliert werden könnte, um ihn zu verkürzen, oder dass das, was Sie benennen, zu viel bewirkt und in mehrere Dinge umgestaltet werden sollte.
Vermeiden Sie Akronyme
Vermeiden Sie Akronyme und Abkürzungen, außer allgemein bekannten wie HTML. Elon Musk schickte im Mai 2010 eine E-Mail mit dem Titel "Acronyms Seriously Suck" an alle SpaceX-Mitarbeiter:
Es gibt eine schleichende Tendenz, bei SpaceX erfundene Akronyme zu verwenden. Die übermäßige Verwendung von erfundenen Akronymen ist ein erhebliches Hindernis für die Kommunikation, und es ist unglaublich wichtig, die Kommunikation während unseres Wachstums gut zu halten. Individuell mögen einige Akronyme hier und da nicht so schlecht erscheinen, aber wenn tausend Leute diese erfinden, wird das Ergebnis im Laufe der Zeit ein riesiges Glossar sein, das wir neuen Mitarbeitern herausgeben müssen. Niemand kann sich tatsächlich an all diese Akronyme erinnern und die Leute wollen in einer Besprechung nicht dumm erscheinen, also sitzen sie einfach in Unwissenheit da. Dies ist besonders schwierig für neue Mitarbeiter.
Das muss sofort aufhören, sonst werde ich drastische Maßnahmen ergreifen - ich habe im Laufe der Jahre genug gewarnt. Sofern ein Akronym nicht von mir genehmigt wurde, sollte es nicht in das SpaceX-Glossar aufgenommen werden. Wenn es ein Akronym gibt, das nicht vernünftigerweise gerechtfertigt werden kann, sollte es beseitigt werden, wie ich es in der Vergangenheit gefordert habe.
Beispielsweise sollten für Prüfstände keine Bezeichnungen "HTS" (horizontaler Prüfstand) oder "VTS" (vertikaler Prüfstand) vorhanden sein. Diese sind besonders dumm, da sie unnötige Wörter enthalten. Ein "Stand" an unserem Teststandort ist offensichtlich ein Teststand. VTS-3 besteht aus vier Silben im Vergleich zu "Tripod" (zwei). Die Version mit dem blutigen Akronym dauert also länger als der Name!
Der Schlüsseltest für ein Akronym ist die Frage, ob es der Kommunikation hilft oder schadet. Ein Akronym, das die meisten Ingenieure außerhalb von SpaceX bereits kennen, wie z. B. die grafische Benutzeroberfläche, ist in Ordnung. Es ist auch in Ordnung, ab und zu ein paar Akronyme / Kontraktionen zu erfinden, vorausgesetzt, ich habe sie genehmigt, z. B. MVac und M9 anstelle von Merlin 1C-Vacuum oder Merlin 1C-Sea Level, aber diese müssen auf ein Minimum beschränkt werden.
Ich stimme ihm zu.
Lesbarkeit
Code sollte so leicht zu lesen sein wie Prosa. Wählen Sie Wörter aus, für die Sie einen Artikel oder ein Buch schreiben möchten. Beispielsweise ist eine Eigenschaft mit dem Namen TotalAmount auf Englisch besser lesbar als AmountTotal .
Implementierungsdetails ausblenden
Hier geht es mehr um objektorientiertes Design, aber es beeinträchtigt die Lesbarkeit erheblich, wenn Implementierungsdetails verfügbar gemacht werden. Versuchen Sie, Methoden mit folgenden Namen nicht verfügbar zu machen:
initializeinitcreatebuild
Domänensprache
Der Code sollte dieselben Namen verwenden wie das automatisierte Geschäfts- oder Domänenmodell.
Wenn ein Reiseveranstalter beispielsweise "Veranstaltungsort" als allgemeinen Namen für Cafés, Hotels und Touristenattraktionen verwendet, ist es eine schlechte Idee, "Ort" im Code zu verwenden, da Sie und Ihre Benutzer zwei verschiedene Sprachen sprechen, was die Sache komplizierter macht als es sollte.
Eine solche Sprache wird oft als "Allgegenwärtige Sprache" bezeichnet. Weitere Informationen finden Sie im Minibuch " Domain Driven Design Quickly " von InfoQ.
Englisch
Die meisten Programmiersprachen verwenden Englisch für integrierte Konstrukte, und es wird empfohlen, die Dinge auch auf Englisch zu benennen. Für einen Entwickler ist es äußerst wichtig, zumindest auf der Grundstufe Englisch zu lernen und, was noch wichtiger ist, über ein gutes Vokabular zu verfügen, mit dem man einen guten Namen finden kann.
Einige nützliche Tools:
Referenzen