9 Richtlinien für die Erstellung aussagekräftiger Namen

Benennung ist subjektiv und situativ, es ist eine Kunst, und wie bei den meisten Künsten entdecken wir Muster. Ich habe viel durch das Lesen von Code anderer gelernt. In diesem Artikel habe ich 9 Richtlinien zusammengestellt, die ich mir gewünscht hätte, dass andere ihnen gefolgt wären, als ich ihren Code las.

Wenn ein Softwareingenieur eine Klasse öffnet, sollte er anhand der Namen die Verantwortlichkeiten der Klasse kennen. Ja, ich weiß, dass Benennung nur eine Speiche des Rades ist, physische und logische Strukturen spielen auch eine wichtige Rolle beim Verständnis des Codes, ebenso wie die Komplexität. In diesem Artikel konzentriere ich mich nur auf die Benennung, da ich glaube, dass sie die größte Auswirkung auf das Verständnis des Codes hat.

Typ nicht einbeziehen, es sei denn, er verdeutlicht die Absicht

Ein Typ kann alles sein, von einem Programmiertyp (String, Int, Decimal) bis zu einer Gruppierung von Verantwortlichkeiten (Util, Helper, Validator, Event usw.). Oft ist es eine Klassifizierung, die keine Absicht ausdrückt.

Schauen wir uns ein Beispiel an: Der Name StringHelper drückt nicht viel aus. Ein String ist ein Systemtyp, und Helper ist vage, StringHelper spricht mehr zum „Wie” als zur Absicht. Wenn wir stattdessen den Namen in DisplayNameFormatter ändern, erhalten wir ein klareres Bild der Absicht. DisplayName ist sehr spezifisch, und Formatter drückt das Ergebnis aus. Formatter kann ein Typ sein oder auch nicht, aber das spielt keine Rolle, da es die Absicht ausdrückt.

Es gibt immer Ausnahmen; zum Beispiel in ASP.Net MVC müssen Controller mit „Controller” enden, sonst funktioniert die Anwendung nicht. Bei Verwendung von Paradigmen wie Domain Driven Design (DDD) haben Namen wie „Services”, „Repository”, „ValueType” und „Model” eine Bedeutung in DDD und drücken Verantwortlichkeit aus.

Zum Beispiel impliziert UserRepository, dass Benutzerdaten abgerufen und in einem Datenspeicher gespeichert werden.

Vermeiden Sie Metaphern

Metaphern sind kulturell, und Ingenieure aus anderen Kulturen verstehen die Absicht möglicherweise nicht.

Häufige Metaphern in den Vereinigten Staaten:

• Beating a dead horse
• Chicken or the egg
• Elephant in the room

Häufige Metaphern in Neuseeland:

• Spit the dummy
• Knackered
• Hard yakka

Verwenden Sie Verben

Steve Yegge schrieb einen (sehr langen) Blogbeitrag über die Verwendung von Verben statt Substantiven.

Sein Punkt ist, Verben zu verwenden, Anwendungen bestehen aus Substantiven, aber Substantive tun nichts. Systeme sind nutzlos mit nur Substantiven, stattdessen drücken Sie Aktion in Namen von Methoden aus.

Zum Beispiel drückt UserAuthentication*(Substantiv).AuthenticateUser(Aktion/Verb)* die Aktion der Überprüfung der Anmeldedaten eines Benutzers aus.

Seien Sie beschreibend

Seien Sie beschreibend, je mehr Details, desto besser – drücken Sie die Verantwortlichkeit im Namen aus.

Fragen Sie sich selbst: Was ist das eine, das diese Klasse oder Funktion gut macht?

Wenn Sie Schwierigkeiten haben, einen Namen zu finden, könnte die Klasse oder Funktion mehr als eine Verantwortlichkeit haben und verstößt somit gegen das Single Responsibility Principle.

Verlassen Sie sich nicht auf Kommentare für die Absicht

Kommentare sind eine großartige Möglichkeit, zusätzlichen Kontext zum Code bereitzustellen, aber verlassen Sie sich nicht auf Kommentare. Die Namen von Klassen und Methoden sollten für sich selbst sprechen.

In Refactoring: Improving the Design of Existing Code von Martin Fowler, Kent Beck, John Brant, William Opdyke und Don Roberts:

… Kommentare werden oft als Deodorant verwendet. Es ist überraschend, wie oft man auf dicht kommentierten Code schaut und bemerkt, dass die Kommentare dort sind, weil der Code schlecht ist.

Ein weiteres wunderbares Zitat der Autoren von „In Refactoring”:

Wenn Sie das Bedürfnis verspüren, einen Kommentar zu schreiben, versuchen Sie zunächst, den Code so umzugestalten, dass jeder Kommentar überflüssig wird. Seite 88

Viele Male, wenn der Code umgestaltet und in eine Methode eingekapselt wird, werden Sie feststellen, dass es andere Orte gibt, an denen es möglich ist, die neue Methode zu nutzen, Orte, die Sie bei der Verwendung der neuen Methode nie erwartet hätten.

Manchmal muss der Verbraucher beim Aufrufen einer Methode etwas Besonderes über die Methode wissen. Wenn diese Besonderheit Teil des Namens ist, muss der Verbraucher den Quellcode nicht überprüfen.

Hier ist ein Beispiel für die Einbeziehung eines Kommentars in einen Namen.

Mit Kommentaren:

// without tracking
var user = GetUserByUserId(userId);

Umgestaltet, um den Kommentar in den Methodennamen einzubeziehen:

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

Andere Ingenieure wissen jetzt, dass diese Methode kein Tracking hat, bevor sie entweder den Quellcode lesen oder den Kommentar finden müssten.

Kommentare sollten Ihre letzte Verteidigungslinie sein. Wenn möglich, lehnen Sie sich auf andere Wege, um die Absicht auszudrücken, einschließlich der Verwendung von physischer und logischer Struktur und Namen, um die Absicht zu vermitteln.

Vermeiden Sie Namen mit mehrdeutiger Bedeutung

Vermeiden Sie Namen mit mehrdeutiger Bedeutung. Die Bedeutung mehrdeutiger Namen ändert sich von Projekt zu Projekt, was es für einen neuen Ingenieur schwieriger macht, die Absicht zu verstehen.

Hier ist eine Liste häufiger mehrdeutiger Namen:

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

Verwenden Sie die gleiche Sprache wie die Geschäftsdomäne

Verwenden Sie die gleiche Terminologie im Code wie in der Geschäftsdomäne. Dies ermöglicht es Ingenieuren und Fachexperten (SME), Ideen leicht zu kommunizieren, da sie das gleiche Vokabular teilen. Wenn es kein gemeinsames Vokabular gibt, findet eine Übersetzung statt, die unweigerlich zu Missverständnissen führt.

In einem Projekt, an dem ich arbeitete, begann das Unternehmen mit „Pupil” und wechselte dann zu „Student”. Die Softwareingenieure aktualisierten die Software nie, um die Änderung der Terminologie widerzuspiegeln. Als neue Ingenieure zum Projekt hinzukamen, glaubten die meisten, dass Pupil und Student unterschiedliche Konzepte waren.

Verwenden Sie Branchenjargon

Verwenden Sie nach Möglichkeit Terminologie, die in der gesamten Softwareindustrie eine Bedeutung hat.

Die meisten Softwareingenieure denken sofort an das Factory-Pattern, wenn sie etwas mit dem Namen „Factory” sehen.

Die Verwendung bestehender Anwendungsparadigmen wie „Clean Architecture” und „Domain Driven Design” erleichtert den Ideenaustausch und schafft eine gemeinsame Sprache für Ingenieure, um Ideen untereinander zu kommunizieren.

Die schlimmste mögliche Benennung ist die Übernahme von branchenweit verwendeter Terminologie und die Vergabe einer anderen Bedeutung.

Bei der Benennung von Booleans…

Boolesche Namen sollten immer eine Antwort auf eine Frage mit einem Wert von entweder wahr oder falsch sein.

Zum Beispiel isUserAuthenticated, die Antwort ist entweder ja (true) oder nein (false)

Verwenden Sie Wörter wie:

• Has
• Does
• Is
• Can

Vermeiden Sie negierte Namen, zum Beispiel:

Ein negierter Variablenname:

var IsNotDeleted = true; // this is confusing

if(!IsNotDeleted) { // it gets even more confusing when the value is negated
  //Do magic
}

Ohne negierter Variablenname:

var IsDeleted = true; // this is confusing

if(!IsDeleted) { 
  //Do magic
}

Abschließend

Die Wahl aussagekräftiger Namen ist entscheidend für die Kommunikation von Absicht, Design und Domänenwissen an den nächsten Ingenieur. Oft arbeiten wir an Code, um Fehler zu beheben oder neue Funktionen zu integrieren, und wir kompilieren ständig Code in unserem Kopf, um zu verstehen, wie er funktioniert. Benennung gibt uns Hinweise darauf, was der vorherige Ingenieur dachte. Ohne diese Kommunikation zwischen den vergangenen und zukünftigen Ingenieuren behindern wir uns selbst beim Wachstum der Anwendung. Möglicherweise verurteilen wir das Projekt zum Scheitern.