it-swarm.dev

Aussagekräftige, präzise Richtlinien für die Benennung von Methoden

Vor kurzem 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 weiß, dass ich jeder Methode clevere Namen zuweisen möchte, um das Lernen zu erleichtern, aber ich muss sie auch verwenden prägnante Namen, damit sie auch leicht zu schreiben sind.

Ich habe über einige Richtlinien zur Benennung nachgedacht. Mir sind viele Richtlinien bekannt, die sich nur um Buchstaben oder einfache Notizen kümmern. Hier kümmere ich mich um Richtlinien für eine aussagekräftige und dennoch präzise Benennung.

Dies könnte beispielsweise Teil der Richtlinien sein, die ich betreue:

  • Verwenden Sie Hinzufügen, wenn ein vorhandenes Element zu 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 Element von einem Ziel entfernt werden soll. Verwenden Sie Löschen, wenn ein Element 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, würde ich gerne 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 meine zweite Sprache. Ich muss über solche Dinge informiert werden.

25
000

Benennung. Eines der schwierigsten Dinge bei der Softwareentwicklung :)

Wenn ich etwas nennen, hier ist meine Reihe von Prioritäten:

  • Folge den Redewendungen meiner Sprache. Ruby mag Unterstriche. Javascript mag Kamelfälle. Welche Sprache auch immer Sie verwenden, 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 es, Implementierungsdetails preiszugeben. Angenommen, einer Variablen wird ein Typ vorangestellt.
  • Verwendet nicht mehr Zeichen als nötig, ohne die vorherigen Richtlinien zu verletzen.

Offensichtlich ist dies ein eher vereinfachter Ansatz. Die Benennung ist nuanciert.

Für weitere Recherchen würde ich empfehlen, The Art of Readable Code zu lesen, da es einige ausgezeichnete, prägnante Ratschläge zur Benennung von Methoden bietet. Für noch mehr Forschung kann ich Bob Martins Clean Code nicht weiter empfehlen

34
Zee

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 besteht darin, die Namenskonvention und den Stil zu vergessen, als ob es sich um eine separate Sache handelt, die separat festgelegt werden muss, und sich stattdessen darauf zu konzentrieren, alles in Ihrem System basierend auf dem zu benennen, was es tatsächlich darstellt. Methodennamen sind in der Regel prägnant, wenn Sie die Funktionalität jeder Methode so einschränken, dass sie nur eines fiktiv ausführt, und wenn Ihr Methodenname tatsächlich das beschreibt, was die Methode tun soll.

Variablen, Felder, Klassen- und Dateinamen sind etwas anderes. Ich würde vorschlagen, dass Sie, wenn die Variablennamen zu lang werden, versuchen, diese Elemente entweder zu detailliert zu beschreiben, oder sie stellen etwas Komplexes dar, das entweder in kleinere Teile zerlegt oder 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 unübersichtlich sind, dass sie ihren Wert verlieren.

7
S.Robins

Für mich bedeutet das Finden eines guten Namens für etwas immer, dass ich es als Objekt betrachte, das seine Existenz rechtfertigen muss. Frag dich selbst:

  • Was macht die Klasse/Methode/Variable, d. H. Was ist ihr umfassenderer Zweck und wofür ist sie?
  • Was genau muss es über seinen Zweck kommunizieren, d. H. Was ist der wesentliche Teil, den der Name enthalten muss?

Die meisten Entwickler würden zustimmen, dass Lesbarkeit immer von größter Bedeutung ist, wenn es um die Benennung geht. Schreiben Sie nicht nur Code, damit Sie wissen, was Sie meinen, während Sie ihn schreiben, sondern schreiben Sie ihn so, dass jemand, der den Code zu einem späteren Zeitpunkt zum ersten Mal betrachtet, weiß, was Sie gemeint haben, ohne zu viel 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 selbstdokumentierend sein, dh Ihre Benennung sollte deutlich machen, was etwas bewirkt. Wenn Sie erklären müssen, was eine Codezeile in einem Kommentar bewirkt, und das Umbenennen nicht ausreichend verbessert, sollten Sie ernsthaft in Betracht ziehen, diese Zeile in eine neue Methode mit einem entsprechend beschreibenden Namen umzuwandeln, damit Sie die ursprüngliche Methode, die Neuer Methodenaufruf beschreibt, was passiert. Hab keine Angst, 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. Vermeiden Sie bis auf einige offensichtliche Ausnahmen wie x/y-Koordinaten und häufig verwendete Akronyme Einzelzeichennamen und Abkürzungen. Etwas "bkBtn" anstelle von "backButton" zu nennen, mag einen Zweck gehabt haben, als Namen auf 8 Zeichen beschränkt waren und Dinosaurier die Erde durchstreiften, aber in diesen Tagen mit Code-Vervollständigung gibt es wirklich keine Entschuldigung für Abkürzungen.

Lassen Sie Ihren Code, soweit es Ihre Sprache zulässt, wie einen englischen Satz lesen. Objekte verwenden Substantive, Methoden verwenden Verben. Boolesche Methoden beginnen normalerweise mit "ist", aber es gibt viele andere Optionen, die die Bedeutung je nach Anwendungsfall noch besser vermitteln, z. B. "kann", "sollte" oder "tut". 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 gerne wie möglich in andere Sprachen übernehmen möchte, sind das Präfixieren des Namens der Schleifenparameter 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 ein wenig Wissen über Java wie folgt) lesbar sein:

Um festzustellen, ob Sie eine Liste einiger Namen (die Zeichenfolgen sind) abkürzen sollten, durchlaufen Sie einige Namen und bestimmen Sie für jeden Namen, ob er zu lang ist. Wenn ja, geben Sie true zurück. Wenn keine zu lang ist, geben Sie false zurück.

Vergleichen Sie den obigen Code mit der bloßen Benennung des Arguments strings und der Schleifenvariablen string, insbesondere bei einer komplexeren Methode. Sie müssten genau hinsehen, um den Unterschied zu erkennen, anstatt dass die Verwendung anhand eines Blicks auf den Namen offensichtlich wird.

6

Machen Sie sich keine Sorgen über 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. Verwenden Sie beispielsweise Find anstelle von Retrieve.

Ebenso wichtig sind auch die Namen, die Sie für Ihre Klassen wä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);

da der aus dem Klassennamen User erhaltene Kontext dem Programmierer mitteilt, dass Find() zum Auffinden eines bestimmten Personentyps, des Benutzers Ihres Systems, dient. Die Version, die die Klasse Person verwendet, gibt Ihnen keinen Zusammenhang darüber, warum Sie die Methode überhaupt erst verwenden müssten.

3
Charles Lambert

Das Finden einer guten Benennung ist immer ein Kompromiss zwischen mehr 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. Durch die Verwendung einer englischsprachigen Syntax wird das Lesen von Code "fließender", da jedes Mal, wenn ein Schlüsselwort gefunden wird, keine "gebrochenen Leseregeln" vorliegen.

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

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 (konzeptionell), während Objekte nach dem benannt werden, was sie are for.

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

3

Sehen Sie sich an, wie andere auf Ihrer Plattform dies tun - einige der größeren Player verfügen möglicherweise sogar über Codestil- und Namensrichtlinien.

Einige Plattformen bevorzugen Kurznamen (zum Beispiel ist in der Win32 C-API _tcsstr Die Funktion, eine Zeichenfolge innerhalb einer Zeichenfolge zu finden - ist das nicht offensichtlich?), Andere bevorzugen die Lesbarkeit zugunsten der Kürze (bei Apple) Das Cocoa-Framework für Objective-C, die Methode zum Ersetzen eines Teilstrings in einem String durch einen anderen String und zum Zurückgeben des Ergebnisses als Kopie, heißt stringByReplacingOccurrencesOfString: withString:). Ich finde letzteres viel einfacher zu verstehen und nur mäßig schwieriger zu schreiben (insbesondere bei Code-Vervollständigung).

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

1
fzwo
  1. Nehmen Sie Englisch an, es sei denn, jeder Entwickler, der jemals an diesem Code arbeitet, spricht dieselbe nicht-englische Sprache.

  2. Studie allgemein akzeptierte Namenskonventionen und -stile. Ihr Leitprinzip sollte Klarheit sein. Stile unterscheiden sich je nach Programmiersprache.

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

1
Robert Harvey
  1. Präfix verwenden. Wenn eine Reihe von Methoden verwendet wird, um etwas Ähnliches zu tun, oder auf irgendeine Weise gruppiert werden kann, setzen Sie ein gemeinsames Präfix vor ihre Namen, um zu zeigen, was diese Methoden gemeinsam haben.
  2. Verwenden Sie keine unklare Abkürzung, wenn andere die Namen sofort verstehen sollen (wichtig für die API-Benennung).
0
neuron