9 Richtlinien für die Erstellung aussagekräftiger Namen

Namensgebung ist subjektiv und situationsabhängig, es ist eine Kunst, und wie bei den meisten Künsten entdecken wir Muster. Ich habe viel durch das Lesen des Codes anderer gelernt. In diesem Artikel habe ich 9 Richtlinien zusammengestellt, die ich mir gewünscht hätte, dass andere sie befolgt hätten, als ich ihren Code las.

Wenn eine Software-Ingenieurin eine Klasse öffnet, sollte sie basierend auf den Namen die Verantwortlichkeiten der Klasse kennen. Ja, ich weiß, dass Namensgebung nur eine Speiche des Rades ist, physische und logische Strukturen spielen ebenfalls eine bedeutende Rolle beim Verstehen des Codes, ebenso wie die Komplexität. In diesem Artikel konzentriere ich mich nur auf die Namensgebung, weil ich denke, dass sie den größten Einfluss auf das Verstehen 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 hin zu einer Gruppierung von Verantwortlichkeiten (Util, Helper, Validator, Event, etc.). 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 zu DisplayNameFormatter ändern, erhalten wir ein klareres Bild der Absicht. DisplayName ist sehr spezifisch, und Formatter drückt das Ergebnis aus. Formatter mag ein Typ sein oder auch nicht, aber das spielt keine Rolle, weil es die Absicht ausdrückt.

Es gibt immer Ausnahmen; zum Beispiel müssen in ASP.Net MVC Controller mit “Controller” enden, oder die Anwendung funktioniert nicht. Bei der 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.

Metaphern vermeiden

Metaphern sind kulturell bedingt, und Ingenieure aus anderen Kulturen verstehen möglicherweise die Absicht 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

Verben verwenden

Steve Yegge schrieb einen (sehr langen) Blog-Post über die Verwendung von Verben anstelle von Substantiven.

Sein Punkt ist, Verben zu verwenden, Anwendungen bestehen aus Substantiven, aber Substantive tun keine Dinge. Systeme sind nutzlos mit nur Substantiven, drücken Sie stattdessen 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.

Beschreibend sein

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

Fragen Sie sich, was ist das eine, was 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 somit das Single Responsibility Principle verletzen.

Sich nicht auf Kommentare für die Absicht verlassen

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

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 sich dicht kommentierten Code ansieht und bemerkt, dass die Kommentare da sind, weil der Code schlecht ist.

Ein weiteres wunderbares Zitat von den “In Refactoring” Autoren:

Wenn Sie das Bedürfnis verspüren, einen Kommentar zu schreiben, versuchen Sie zuerst, den Code zu refaktorieren, sodass jeder Kommentar überflüssig wird. Seite 88

Oft, wenn der Code refaktoriert und in eine Methode eingekapselt wird, finden Sie andere Stellen, wo es möglich ist, die neue Methode zu nutzen, Stellen, die Sie nie bei der Verwendung der neuen Methode erwartet hätten.

Manchmal muss der Verbraucher beim Aufrufen einer Methode etwas Bestimmtes über die Methode wissen, wenn diese Besonderheit Teil des Namens ist, dann 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);

Refaktoriert, um den Kommentar in den Methodennamen einzubeziehen:

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

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

Kommentare sollten Ihre letzte Verteidigungslinie sein, wenn möglich, nutzen Sie andere Wege, um Absicht auszudrücken, einschließlich der Verwendung physischer und logischer Struktur und Namen, um Absicht zu vermitteln.

Sich von Namen mit mehrdeutiger Bedeutung fernhalten

Vermeiden Sie Namen mit mehrdeutigen Bedeutungen. Die Bedeutung mehrdeutiger Namen ändert sich von Projekt zu Projekt, was das Verstehen der Absicht für einen neuen Ingenieur schwieriger macht.

Hier ist eine Liste häufiger mehrdeutiger Namen:

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

Die gleiche Sprache wie die Geschäftsdomäne verwenden

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, weil sie das gleiche Vokabular teilen. Wenn es kein gemeinsames Vokabular gibt, findet Ü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 Software-Ingenieure aktualisierten die Software nie, um die Änderung in der Terminologie zu reflektieren. Als neue Ingenieure dem Projekt beitraten, glaubten die meisten, dass Pupil und Student verschiedene Konzepte waren.

Branchenjargon verwenden

Verwenden Sie wenn möglich Terminologie, die in der gesamten Software-Branche Bedeutung hat.

Die meisten Software-Ingenieure denken, wenn sie etwas namens “factory” sehen, sofort an das Factory-Pattern.

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 schlechteste mögliche Namensgebung ist die Übernahme branchenweiter Terminologie und die Vergabe einer anderen Bedeutung.

Bei der Benennung von Booleans…

Boolean-Namen sollten immer eine Antwort auf eine Frage sein, mit ihrem Wert entweder wahr oder falsch.

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; // das ist verwirrend

if(!IsNotDeleted) { // es wird noch verwirrender, wenn der Wert negiert wird
  //Do magic
}

Ohne negierten Variablennamen:

var IsDeleted = true; // das ist verwirrend

if(!IsDeleted) { 
  //Do magic
}

Zum Abschluss

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 Defekte zu beheben oder neue Features einzubauen, und wir kompilieren ständig Code in unserem Kopf und versuchen zu verstehen, wie er funktioniert. Namensgebung 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.