Arbeiten an besserer Benennung

Es gibt ein Zitat, das Sie, wie ich wette, alle schon oft gehört haben. Sie kennen es. Das, das uns daran erinnert, wie schwer Namensgebung ist.

Lasst uns über Namen reden.

Wir reden oft darüber, wie schwer das Benennen ist, aber es ist seltener, dass Leute darüber reden, wie sie darin besser werden. Selbst Benennungsphilosophien geben Struktur für die Benennung, aber sie wählen keine Namen für Sie aus. Namen sind mehr als nur eine harte Sache, in der wir uns unnötigerweise verfangen. Sie sind essentiell für guten Code. Gute Namen können eine Codebasis leicht verständlich und handhabbar machen. Schlechte Namen sind schwer zu verstehen oder, schlimmer noch, fehleranfällig.

Namensbeispiele

Betrachten wir einige Beispiele in JavaScript.

function processData(data) {
  var result = JSON.parse(data);
  return result;
}

Wenn man nur den Funktionsnamen, den Parameternamen und die zurückgegebene Variable liest, sieht man, dass processData data erhält und ein result zurückgibt. Diese Namen haben dem Leser fast keinen Informationsgewinn hinzugefügt. Code wie dieser ist leicht zu schreiben, wenn man ihn einfach zum Laufen bringen möchte oder wenn man flexibel auf Änderungen reagieren will, und das ist in Ordnung. Es ist immer eine gute Idee, seinen Code mit frischem Blick zu überprüfen, um Dinge zu beheben, und Namen sollten auf Ihrer Checkliste für Qualität stehen.

Hier ist eine beschreibendere Art, wie wir das letzte Beispiel hätten schreiben können

function parseJson(string) {
  var jsonObject = JSON.parse(string);
  return jsonObject;
}

Technologie ist eines der am stärksten von Abkürzungen und Akronymen geprägten Felder, und sie sind der Schlüssel zu großartigen Namen. FTP ist leichter zu lesen und zu verstehen als „File Transfer Protocol“. In manchen Fällen kann der Leser jedoch ausgeschlossen werden.

Hier ist ein Beispiel, bei dem die Abkürzungen für den Entwickler, der den Code schreibt, praktisch sind, aber nicht so hilfreich für jeden anderen, der ihn lesen oder dazu beitragen muss.

function cts(con, ack) {
  if (con && ack) {
    return true;
  }
  else {
    return false;
  }
}

Oft lese ich Code mit einem Akronym und muss zu meinem Webbrowser wechseln, um eine Suche durchzuführen, nur um Ergebnisse für Automodelle zu finden. Ein perfektes Beispiel dafür ist cts, das viele Cadillac-Ergebnisse liefert. ack taucht zwar bei einer Suche auf, aber ich möchte es lieber nicht in meinem Texteditor lassen. con kann auf viele Arten missverstanden werden. Ist es eine Verbindung? Eine Zählung? Ein Behälter? Vielleicht ist es ein Betrug. Diese Dinge sind vielleicht offensichtlich, wenn man mit der Codebasis vertraut ist, aber es erhöht die Lernkurve für diejenigen, die neu im Projekt sind. Ein paar zusätzliche Sekunden können Lesern über Jahre hinweg mehrere Minuten sparen.

Hier ist das vorherige Beispiel ohne Abkürzungen geschrieben

function clearToSend(connectionExists, acknowledgementStatus) {
  if (connectionExists && acknowledgementStatus) {
    return true;
  }
  else {
    return false;
  }
}

Wenden wir uns einigen HTML-Beispielen zu, denn HTML ist vielleicht die sprachlich am stärksten von Namen geprägte Sprache von allen.

<section class="new-promotion-parent">
  <img class="logo" src="small-square-logo-monochrome.png"/>
  <div class="get-your-coupon">
    <p>Get Your Coupon</p>
  </div>
</section>

Wir können uns vorstellen, dass das Wort „new“ hier wahrscheinlich verwendet wurde, weil einem Designer gesagt wurde, das Element promotion-parent zu aktualisieren, aber auch die Unterstützung für die bestehende Klasse beizubehalten, vielleicht für alten HTML-Code. Der Begriff „new“ ist eine genaue Beschreibung für die ersten paar Monate, aber im Laufe der Zeit wird er immer ironischer. Eine bessere Idee wäre es vielleicht, eine separate Klasse hinzuzufügen, die beschreibt, was neu ist. Zum Beispiel, wenn ein neues Flat Design implementiert wird, dann könnte ein Klassenname wie flat-design funktionieren. Als Bonus können Sie die CSS der bestehenden Klasse promotion-parent überschreiben lassen, wenn Sie einige der Stile wiederverwenden möchten.

Ähnlich scheint logo zunächst ein sinnvoller Klassenname zu sein. Unvermeidlich kommt jedoch irgendwann ein zweites Logo, das den Namen alt-logo erhält. Die Logos kommen immer wieder, und damit auch die immer schlechteren Namen. Die meisten Assets haben mehrere Varianten, wie z.B. verschiedene Formen, Größen, Farbschemata und mehr. Das bedeutet, dass small-square-logo-monochrome auch kein großartiger Klassenname wäre, da das Bild selbst ausgetauscht werden kann, ohne dass der Klassenname obsolet wird. Eine bessere Idee wäre ein Name, der die Rolle des Assets beschreibt und nicht den Typ oder das Aussehen.

Hier wurde die Sprache des Divs verwendet, um das Div get-your-coupon zu benennen. Der Inhalt eines HTML-Dokuments soll sich ständig weiterentwickeln; Namen nicht. Ein Gutscheincode mag heute ein E-Mail-Anmeldeformular sein, während die gleichen Stile und Funktionalitäten beibehalten werden. HTML ist ein Ort, an dem Namen oft zu spezifisch statt zu vage sind.

Hier ist derselbe HTML-Code, der die Vorschläge berücksichtigt

<section class="flat-design promotion-parent">
  <img class="promotion-branding-image" src="small-square-logo-monochrome.png"/>
  <div class="primary-promotion-text">
    <p>Get Your Coupon</p>
  </div>
</section>

Wir können uns sogar die Namen in einer Datenbank ansehen, um bessere Benennungen zu erzielen. Tabellen werden oft unzählige Male in einer Anwendung in sehr unterschiedlichen Kontexten verwendet.

Hier ist eine vereinfachte Datenbanktabelle

CREATE TABLE `book` (
  `id` int(12) NOT NULL,
  `title` varchar(50) NOT NULL,
  `author` varchar(50) NOT NULL,
  `type` bit(1) NOT NULL,
  `sort` int(12) NOT NULL,
  `order` varchar(25) NOT NULL,
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Was bedeutet type im Kontext von Büchern? Meint es Belletristik oder Sachbuch? Meint es Taschenbuch oder Hardcover? Vielleicht bedeutet es physisch oder digital?

Die Spalte sort ist ebenso verwirrend. Repräsentiert sie aufsteigend (ASC) oder absteigend (DESC)? Repräsentiert sie, nach welcher Spalte sortiert wird? Vielleicht entscheidet sie, ob die Sortierung aktiv ist? Oder vielleicht entscheidet sie, die Bücher in einer anderen alternativen Reihenfolge anzuzeigen?

Und dann ist da noch order. Abgesehen davon, dass sie ebenso mehrdeutig ist, ist „order“ ein reserviertes Wort in MySQL und vielen anderen Sprachen. Sie können dies in MySQL mit Backticks (`) umgehen, aber es ist wahrscheinlich eine bessere Idee, die Verwendung von reservierten Wörtern ganz zu vermeiden.

Hier ist, wie die Tabelle in einer beschreibenderen Weise geschrieben werden könnte

CREATE TABLE `book` (
  `id` int(12) NOT NULL,
  `title` varchar(50) NOT NULL,
  `author` varchar(50) NOT NULL,
  `cover_type` bit(1) NOT NULL,
  `sort_order` int(12) NOT NULL,
  `purchase_order_number` varchar(25) NOT NULL,
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Namenskonventionen

Lasst uns über Namenskonventionen reden.

if (oldmanshaven) {
  return true;
}

Haben Sie das als „Old Mans Haven“ oder „Old Man Shaven“ gelesen? So oder so zwingt es Sie, innezuhalten und nachzudenken, was sich summiert und eines Tages zu einem Missverständnis führen könnte. PascalCase, camelCase, snake_case, kebab-case sind alles ausgezeichnete Entscheidungen. Nutzen Sie sie, und ebenso wichtig, seien Sie konsistent.

Hier ist derselbe Code in snake_case, der weniger wahrscheinlich missverstanden wird.

if (old_man_shaven) {
  return true;
}

Noch ein Beispiel

if (!isNaN(number)) {
  alert('not a number')
}
else if (!number > 50) {
  alert('number too large')
}
else if (!number < 10) {
  alert('number too small')
}
else {
  // code here
}

Ich habe einige meiner ersten Codezeilen als Inspiration für diesen Beitrag durchgesehen. Ich habe nicht viele schlechte Namen gesehen, weil ich Code auf eine Weise schrieb, die keine Namen verwendete. Ich benutzte sehr wenige Funktionen, selten Zuweisungen und missbrauchte Variablen, indem ich sie für ein Dutzend verschiedener Dinge verwendete. Viele Namen in Ihrem Code zu haben, ist oft ein Zeichen dafür, dass Sie Dinge richtig abstrahieren.

Hier ist ein Beispiel aus meinem Code

function validateNumber(number) {
  var maximumValue = 50;
  var minimumValue = 10;
  if (isNaN(number)) {
    alert('not a number')
    return false;
  }
  if (number > maximumValue) {
    alert('number too large')
    return false;
  }
  if (number < minimumValue) {
    alert('number too small')
    return false;
  }
}

if (validateNumber(number)) {
  // code here
}

Einschränkungen

Das Benennen von Dingen ist eine Kunst, keine Wissenschaft. Es gibt einige Dinge außerhalb des Namens, die bei der Bewertung, ob ein Name gut oder schlecht ist, berücksichtigt werden müssen.

Kontext

Kontext kann generischen Begriffen viel mehr Bedeutung verleihen. Zum Beispiel ist „item“ ein vager Name, aber im Kontext einer Funktion getCustomerSalesOrder() können wir erkennen, dass es sich wahrscheinlich um ein gekauftes Produkt handelt. Eine Funktion, die kurz, fokussiert und kontextbezogen ist, kann den Bedarf an ausführlichen Namen reduzieren. Ich bevorzuge dennoch einen guten Namen. Kontext kann im Laufe der Zeit leicht verschwinden, wenn Funktionen länger werden oder refaktorisiert werden. Namen sind beständigere Bedeutungsträger.

Kommentare

Code-Kommentare sind wichtig für lesbaren Code, aber sie können nicht alles allein tun. Kommentare sollten dort ansetzen, wo Namen aufhören, indem sie Details liefern, die Sie nicht in einen Namen packen können, den Grund für eine bestimmte Vorgehensweise angeben oder sich über eine fehlerhafte Bibliothek beschweren.

/* This refers to a product that was purchased and relates to the customer-sales-order class. */
.product-item {
  display: block;
  text-transform: uppercase;
  width: 100vw;
}

Leselänge

Längere Namen bedeuten mehr zu lesen und breitere Zeilen. Das kann besonders problematisch sein, wenn man tief in ein Array eindringt, wie z.B.

$order_details['customer']['ship_to_address']['default']['street_address']['line_1']

Das gesagt, selbst dieses Strohmann-Beispiel, das ich gerade gegeben habe, ist, obwohl es ausführlich ist, kristallklar und gibt mir keinen Grund, aufzuhören zu lesen, um nachzudenken oder den Rest der Funktion zu überprüfen, um den Kontext zu verstehen.

Namen sind überall im Code

Die meisten Zeichen einer Codedatei sind wahrscheinlich keine Klammern oder Syntax, sondern Namen. Es könnten Variablennamen, Funktionsnamen, HTML-Tags oder Attribute, Datenbanktabellen oder -spalten sein oder alles andere von den unzähligen Dingen, denen wir in einem bestimmten Projekt Namen geben.

Ich kämpfe immer noch damit, Dinge zu benennen. Ich sitze oft erstarrt vor meinem Texteditor und versuche, eine belanglose Variable zu benennen. Ich habe gelernt, dass das wahrscheinlich daran liegt, dass ich es mit etwas Schwierigem zu konzeptualisieren zu tun habe, was es umso wichtiger macht, den richtigen Namen dafür zu finden.