Aussagekräftige Richtlinien für die Benennung von Methoden

Kürzlich habe ich angefangen, ein Open-Source-Projekt zu veröffentlichen, als ich der einzige Benutzer der Bibliothek war, dem die Namen egal waren, aber ich möchte jeder Methode kluge Namen zuweisen, um das Erlernen zu erleichtern, aber ich muss sie auch verwenden prägnante Namen, damit sie auch leicht zu schreiben sind.

Ich habe über einige Richtlinien für die Benennung nachgedacht. Mir sind viele Richtlinien bekannt, bei denen es nur um die Groß- und Kleinschreibung von Buchstaben oder einfache Notizen geht. Hier kümmere ich mich um Richtlinien für eine aussagekräftige und doch prägnante Namensgebung.

Dies könnte zum Beispiel Teil der Richtlinien sein, nach denen ich suche:

• Verwenden Sie Hinzufügen, wenn ein vorhandenes Element einem Ziel hinzugefügt werden soll. Verwenden Sie Erstellen, wenn ein neues Element erstellt und einem Ziel hinzugefügt wird.
• Verwenden Sie Entfernen, wenn ein vorhandenes Objekt von einem Ziel entfernt werden soll. Verwenden Sie Löschen, wenn ein Objekt dauerhaft entfernt werden soll.
• Koppeln Sie AddXXX-Methoden mit RemoveXXX und Pair CreateXXX-Methoden mit DeleteXXX-Methoden, aber mischen Sie sie nicht.

Wie die obigen Beispiele zeigen, möchte ich Online-Material finden, das mir bei Benennungsmethoden und anderen Elementen hilft, die der englischen Grammatik und den Wortbedeutungen entsprechen.

Die obige Anleitung mag für englische Muttersprachler intuitiv sein, aber für mich ist Englisch die zweite Sprache, in der ich über solche Dinge informiert werden muss.

Benennung. Eines der schwierigsten Dinge bei der Softwareentwicklung :)

Wenn ich etwas benenne, sind hier meine Prioritäten:

• Folge den Redewendungen meiner Sprache. Ruby mag Unterstriche. Javascript mag Kamelkasten. Welche Sprache Sie auch sprechen, es ist die Konvention, der Sie folgen müssen.
• Zeigt die Absicht der API an. Es ist nicht "send_http_data", sondern "post_twitter_status".
• Vermeiden Sie die Weitergabe von Implementierungsdetails. Stellen Sie einer Variablen beispielsweise einen Typ voran.
• Verwendet nicht mehr Zeichen als erforderlich, ohne die vorherigen Richtlinien zu verletzen.

Offensichtlich ist dies ein ziemlich simpler Ansatz. Die Benennung ist nuanciert.

Für weitere Nachforschungen empfehle ich das Lesen von The Art of Readable Code , da es einige ausgezeichnete, prägnante Hinweise zur Benennung von Methoden enthält. Für noch mehr Nachforschungen kann ich Bob Martins Clean Code nicht weiter empfehlen

Die Versuchung, einen Stil oder eine Konvention für die Benennung zu kodifizieren, kann in einigen Fällen zu Gewohnheiten führen, die heutzutage als schlechte Praxis gelten, wie zum Beispiel die Verwendung der ungarischen Notation. Die einfache Antwort ist, die Namenskonvention und den Stil zu vergessen, als ob es sich um eine separate Sache handeln würde, die separat festgelegt werden muss, und sich stattdessen darauf zu konzentrieren, alles in Ihrem System anhand dessen zu benennen, was es tatsächlich darstellt. Methodennamen sind in der Regel prägnant, wenn Sie die Funktionalität der einzelnen Methoden so einschränken, dass sie nur eine bestimmte Aufgabe erfüllen, und wenn Ihr Methodenname tatsächlich die Aufgabe beschreibt, die die Methode erfüllen soll.

Variablen, Felder, Klassen- und Dateinamen sind etwas anderes. Ich würde vorschlagen, wenn die Variablennamen zu lang werden, versuchen Sie, diese Elemente entweder zu detailliert zu beschreiben, oder sie stellen etwas Komplexes dar, das entweder in kleinere Teile zerlegt oder möglicherweise abstrakter beschrieben werden sollte Weise.

Am Ende des Tages möchten Sie hässlichen Code mit Namen vermeiden, die eine ganze Zeile einnehmen oder so unansehnlich sind, dass sie ihren Wert verlieren.

Wenn ich einen guten Namen für etwas finde, wird es immer wieder als ein Objekt betrachtet , das seine Existenz rechtfertigen muss. Frag dich selbst:

• Was macht die Klasse / Methode / Variable, dh wozu dient sie im weiteren Sinne und wozu dient sie?
• Was genau muss es mit seinem Zweck kommunizieren, dh was ist der wesentliche Teil, den der Name enthalten muss?

Die meisten Entwickler sind sich einig, dass die Lesbarkeit bei der Benennung immer von größter Bedeutung ist. Schreiben Sie nicht einfach Code, damit Sie wissen, was Sie meinen, während Sie ihn schreiben, sondern damit jemand, der irgendwann in der Zukunft zum ersten Mal auf den Code schaut, weiß, was Sie gemeint haben, ohne zu viel darüber nachdenken zu müssen. Sie werden den Code nur einmal schreiben, aber während seiner Lebensdauer muss er höchstwahrscheinlich viele Male bearbeitet und noch öfter gelesen werden.

Der Code sollte sich selbst dokumentierenDas heißt, Ihre Benennung sollte deutlich machen, was etwas bewirkt. Wenn Sie erläutern müssen, was eine Codezeile in einem Kommentar bewirkt, und das Umbenennen von Elementen nicht ausreichend verbessert, sollten Sie ernsthaft in Erwägung ziehen, diese Zeile in eine neue Methode mit einem entsprechend beschreibenden Namen umzugestalten, damit beim Lesen der ursprünglichen Methode die Neuer Methodenaufruf beschreibt, was gerade passiert. Hab keine Angst davor, lange Namen zu haben. Natürlich sollten Sie keine Romane in Klassen- / Methoden- / Variablennamen schreiben, aber ich möchte lieber, dass ein Name zu lang und beschreibend als zu kurz ist, und ich muss herausfinden, was er tut, indem ich unter die Haube schaue. Mit Ausnahme einiger offensichtlicher Ausnahmen wie X / Y-Koordinaten und häufig verwendeter Akronyme sollten Sie Namen und Abkürzungen mit einzelnen Zeichen vermeiden. Aufrufen von "bkBtn" anstelle von "backButton"

Wenn es Ihre Sprache erlaubt, lassen Sie Ihren Code wie einen englischen Satz lesen. Objekte verwenden Substantive, Methoden verwenden Verben. Boolesche Methoden beginnen normalerweise mit "is", aber es gibt viele andere Optionen, die die Bedeutung je nach Anwendungsfall noch besser vermitteln, z. B. "can", "should" oder "does". Natürlich können nicht alle Sprachen so gut sein wie Smalltalk, aber einige Symbole werden im Allgemeinen als Teile des Satzes verstanden. Zwei Smalltalk-Konventionen, die ich persönlich so oft wie möglich in anderen Sprachen verwenden möchte, sind das Präfixieren des Namens von Schleifenparametern mit "each" und das Präfixieren von Methodenparametern mit dem Artikel "a" (oder "an" oder "some" für Sammlungen). . Dies ist möglicherweise kein allgemeiner Standard in Java, und jeder kann dieses Bit ignorieren. aber ich finde, dass dies die Lesbarkeit von Code erheblich verbessert. Zum Beispiel (Beispiel in Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Dies sollte für Leute mit nur geringen Java-Kenntnissen wie folgt lesbar sein:

Um festzustellen, ob Sie in Betracht ziehen sollten, eine Liste einiger Namen (bei denen es sich um Zeichenfolgen handelt) abzukürzen, durchlaufen Sie einige Namen und bestimmen Sie für jeden Namen, ob er zu lang ist. wenn ja, kehre zurück true; Wenn keiner zu lang ist, kehre zurück false.

Vergleichen Sie den obigen Code, indem Sie nur das Argument stringsund die Schleifenvariable benennen string, insbesondere bei einer komplexeren Methode. Sie müssten genau hinsehen, um den Unterschied zu erkennen, anstatt die Verwendung anhand eines Blicks auf den Namen zu erkennen.

Eine gute Benennung zu finden, ist immer ein Kompromiss zwischen mehreren Faktoren. Sie werden nie ganz zufrieden sein.

Das heißt, auch wenn Ihre Muttersprache nicht so ist, denken Sie daran, dass Englisch die Sprache ist, deren Programmiersprachen Token gebildet werden. Die Verwendung der englischen Syntax macht das Lesen von Code "flüssiger", da bei jedem Auffinden eines Schlüsselworts keine "gebrochenen Leseregeln" vorhanden sind.

Betrachten Sie im Allgemeinen Dinge object.method(parameters), die mit einem Schema wie übereinstimmen subject.verb(complements).

Der entscheidende Punkt, wenn Sie die generische Programmierung unterstützen müssen, ist die Auswahl eines guten und konsistenten Satzes von "Verben" (insbesondere derjenigen, die in generischen Algorithmen verwendet werden müssen).

Bei Substantiven sollten Klassen nach dem benannt werden, was sie are(begrifflich) haben, während Objekte nach dem, was sie haben are for.

Das heißt, zwischen list.add(component)und component.add_to(list)bevorzuge die erste. Im Allgemeinen repräsentieren "aktive transitiven" Verben Aktionen besser in Bezug auf ihre passiven oder reflexiven Gegenstücke. Es sei denn, das Design schränkt Sie ein.

Sorgen Sie sich nicht um die Länge der Methodennamen. Stellen Sie sicher, dass die Methodennamen klar wiedergeben, was sie tun. Dies ist für alles andere von größter Bedeutung. Wenn Sie der Meinung sind, dass der Methodenname zu lang ist, verwenden Sie einen Thesaurus, um ein kürzeres Wort zu finden, das dasselbe bedeutet. Zum Beispiel verwenden Sie Findanstelle von Retrieve.

Ebenso wichtig sind die Namen, die Sie für Ihre Klassen auswählen. Diese bieten viel Kontext beim Betrachten von Methodennamen. Eine Methodensignatur wie folgt:

public User Find(int userId);

ist leichter zu verstehen als:

public Person Find(int personId);

weil der Kontext, der aus dem Klassennamen erhalten Userwird, dem Programmierer mitteilt, dass Find()der Benutzer Ihres Systems zum Auffinden eines bestimmten Personentyps bestimmt ist. Die Version, die die PersonKlasse verwendet, gibt Ihnen keinen Kontext darüber, warum Sie die Methode überhaupt erst verwenden müssten.

Schauen Sie sich an, wie andere auf Ihrer Plattform dies tun - einige der größeren Player haben möglicherweise sogar Richtlinien für den Codestil und die Benennung.

Einige Plattformen bevorzugen kurze Namen (in der Win32 C-API _tcsstrist beispielsweise die Funktion zum Auffinden einer Zeichenfolge in einer Zeichenfolge - ist das nicht offensichtlich?), Andere bevorzugen die Lesbarkeit zugunsten der Kürze (im Apple Cocoa Framework für Objective-C) , die Methode, um eine Teilzeichenfolge in einer Zeichenfolge durch eine andere Zeichenfolge zu ersetzen und das Ergebnis als Kopie zurückzugeben, wird aufgerufen stringByReplacingOccurrencesOfString: withString:). Ich finde letzteres viel einfacher zu verstehen und nur mäßig schwieriger zu schreiben (insbesondere mit Code-Vervollständigung).

Da Sie Code häufiger lesen als schreiben (doppelt wahr für Open Source-Bibliotheken) und das Lesen schwieriger ist als das Schreiben, optimieren Sie das Lesen. Optimieren Sie nur für die Kürze, und nehmen Sie nur so viel wie möglich weg, ohne die Klarheit zu beeinträchtigen.

1. Angenommen, es wird Englisch gesprochen, es sei denn, jeder Entwickler, der jemals an diesem Code arbeitet, spricht dieselbe nicht-englische Sprache.

2. Lesen Sie allgemein akzeptierte Namenskonventionen und -stile. Ihr Leitsatz sollte Klarheit sein. Stile unterscheiden sich je nach Programmiersprache.

3. Mit der Benennung können Sie nichts anfangen, was das Verständnis der Beziehungen zwischen den verschiedenen Objekten in Ihrem Code erleichtert. Dafür benötigen Sie noch gut geschriebene Kommentare und Unterlagen.

1. Präfix verwenden. Wenn eine Reihe von Methoden verwendet wird, um etwas Ähnliches zu tun, oder in irgendeiner Weise zu einer Gruppe zusammengefasst werden kann, setzen Sie vor ihren Namen ein gemeinsames Präfix, um zu zeigen, was diese Methoden gemeinsam haben.
2. Verwenden Sie keine unklare Abkürzung, wenn andere Benutzer die Namen sofort verstehen sollen (wichtig bei der API-Benennung).