21

Ist es nicht interessant, im Code einen fehlplatzierten und nutzlosen Kommentar zu finden?

Wie kann man sehr wenige Kommentare schreiben und den Code trotzdem leicht verständlich halten?

Ein wichtiger Weg ist, den Code selbstdokumentierend zu machen. Wenn Code selbstdokumentierend ist, sind Kommentare nicht nötig, um seine Funktion oder seinen Zweck zu erklären, und er lässt sich außerdem sehr einfach warten.

In diesem Artikel werde ich einige Möglichkeiten vorstellen, Ihren Code selbstdokumentierend zu machen. Im Folgenden finden Sie drei grundlegende Methoden, um Code selbstdokumentierend zu machen:

  • Benennung: Verwenden Sie Namen, um den Zweck von Variablen, Funktionen usw. zu erklären.
  • Funktionen kapseln: Kapseln Sie Code mit spezifischer Funktionalität in eine Funktion, um seinen Zweck zu verdeutlichen.
  • Variablen einführen: Legen Sie Ausdrücke in dedizierte Variablen.

Das mag einfach erscheinen, aber in der Praxis kann es etwas knifflig sein. Zuerst müssen Sie verstehen, wo die Probleme liegen und wo diese Methoden angewendet werden.

Darüber hinaus gibt es neben den oben genannten drei noch einige weitere, breit angewandte Ansätze:

  • Klassen- und Modulschnittstellen: Funktionen in Klassen und Modulen offenlegen, um den Code klarer zu machen.
  • Codegruppierung: Verwenden Sie Gruppen, um verschiedene Codeabschnitte zu unterscheiden.

Als Nächstes werden wir anhand von Beispielen konkret besprechen, wie die oben genannten 5 Methoden in der Praxis angewendet werden.

1. Benennung

Betrachten Sie zunächst einige Beispiele dafür, wie Code klar und selbstdokumentierend wird, wenn Benennung verwendet wird.

1. Umbenennen von Funktionen

Das Benennen von Funktionen ist nicht sehr schwierig; Sie können sich an diese Regeln halten:

  • Vermeiden Sie vage Wörter wie 'handle' oder 'manage' — handleLinks, manageObjects.
  • Verwenden Sie aktive Verben — cutGrass, sendFile —, um anzugeben, dass die Funktion aktiv eine Aktion ausführt.
  • Geben Sie den Rückgabewerttyp an — getMagicBullet, READFILE. Stark typisierte Sprachen können auch Typbezeichner verwenden, um den Rückgabetyp der Funktion anzugeben.

2. Variablen umbenennen

  • Einheiten angeben — wenn es numerische Parameter gibt, können Sie deren Einheiten hinzufügen. Verwenden Sie beispielsweise widthPx statt width, um anzugeben, dass die Einheit von width Pixel ist.
  • Verwenden Sie keine Abkürzungen — a und b sollten nicht als Parameternamen verwendet werden.

2. Kapselung in Funktionen

Schauen Sie sich als Nächstes einige Beispiele an, wie man Code in Funktionen kapselt. Ein Vorteil der Kapselung in Funktionen besteht darin, Code-Wiederholungen zu vermeiden oder die Codestruktur zu verbessern.

1. Code in Funktionen kapseln

Das ist die grundlegendste Form: Kapseln Sie Code in eine Funktion, um ihren Zweck zu verdeutlichen. Raten Sie, was die folgende Codezeile macht:

var width = (value - 0.5) * 16;

Es ist möglicherweise nicht sehr klar; mit einem Kommentar wäre es natürlich vollkommen klar, aber wir können es einfach in eine Funktion kapseln, um Selbstdokumentation zu erreichen...

var width = emToPixels(value);
 
function emToPixels(ems) {
    return (ems - 0.5) * 16;
}

Die einzige Änderung besteht darin, dass der Berechnungsprozess in eine Funktion verschoben wurde. Der Funktionsname drückt klar aus, was sie tut, daher müssen keine Kommentare geschrieben werden. Wenn sie später benötigt wird, kann diese Funktion außerdem direkt aufgerufen werden, was zwei Fliegen mit einer Klappe schlägt und redundante Arbeit reduziert.

2. Bedingte Ausdrücke durch Funktionen ersetzen

If-Anweisungen, die mehrere Operanden enthalten, sind ohne Kommentare schwerer zu verstehen.

if(!el.offsetWidth || !el.offsetHeight) {
}

Kennen Sie den Zweck des obigen Codes?

function isVisible(el) {
    return el.offsetWidth && el.offsetHeight;
}
 
if(!isVisible(el)) {
}

3. Variablen einführen

Schließlich sprechen wir darüber, wie man Variablen einführen kann. Verglichen mit den beiden oben genannten Methoden ist diese möglicherweise weniger nützlich, aber in jedem Fall ist es besser, sie zu kennen, als sie nicht zu kennen.

1. Ausdrücke durch Variablen ersetzen

Schauen Sie sich dieses Beispiel an

if(!el.offsetWidth || !el.offsetHeight) {
}

Dieses Mal ersetzen Sie es, anstatt es in eine Funktion zu kapseln, durch die Einführung von Variablen.

var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}

2. Variablen anstelle von Gleichungen verwenden

Wir können es auch verwenden, um komplexe Formeln klar zu erklären:

return a * b + (c / d);

Ersetzen Sie sie durch Variablen.

var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;

4. Schnittstellen von Klassen und Modulen

Die Schnittstellen von Klassen und Modulen – also die öffentlich zugänglichen Methoden und Eigenschaften – ähneln in gewisser Weise einer Dokumentation, die erklärt, wie man sie verwendet.

Betrachten Sie das folgende Beispiel:

class Box {
    public function setState(state) {
        this.state = state;
    }
 
    public function getState() {
        return this.state;
    }
}

Diese Klasse könnte auch anderen Code enthalten. Ich habe dieses Beispiel absichtlich gewählt, um zu veranschaulichen, wie die öffentliche Schnittstelle selbstdokumentierend sein kann.

Können Sie erkennen, wie diese Klasse aufgerufen wird? Offensichtlich ist es nicht offensichtlich.

Diesen beiden Funktionen sollten sinnvolle Namen gegeben werden, die ihren Zweck ausdrücken. Aber selbst wenn das geschieht, ist uns immer noch nicht ganz klar, wie wir sie verwenden sollen. Dann müssen wir mehr Code lesen oder die Dokumentation konsultieren.

Aber was, wenn wir es so ändern ...

class Box {
    public function open() {
        this.state = open;
    }
 
    public function close() {
        this.state = closed;
    }
 
    public function isOpen() {
        return this.state == open;
    }
}

Ist es nicht viel klarer? Hinweis: Wir haben nur die öffentliche Schnittstelle geändert; ihre interne Repräsentation ist dieselbe wie der ursprüngliche this.state-Zustand.

5. Code-Gruppierung

Die Verwendung von Gruppen zur Unterscheidung verschiedener Codeabschnitte ist ebenfalls eine Form der Selbstdokumentation. Zum Beispiel sollten wir, wie in diesem Artikel dargelegt, Variablen möglichst nahe an ihrer Verwendung definieren und Variablen so weit wie möglich klassifizieren. Dies kann auch verwendet werden, um die Beziehungen zwischen verschiedenen Codegruppen anzugeben, sodass andere leichter erkennen können, welche Codegruppen sie noch verstehen müssen.

Betrachten Sie das folgende Beispiel:

var foo = 1;
 
blah()
xyz();
 
bar(foo);
baz(1337);
quux(foo);

Im Vergleich zu Folgendem:

var foo = 1;
bar(foo);
quux(foo);
 
blah()
xyz();
 
baz(1337);

Fasse alle Verwendungen von foo zusammen, und du kannst die Beziehungen auf einen Blick sehen. Aber manchmal müssen wir dazwischen einige andere Funktionen aufrufen. Wenn möglich, versuche daher, Code-Gruppierung zu verwenden; wenn nicht, erzwinge es nicht.

6. Weitere Vorschläge

  • Verwende keine seltsamen Markierungen; die folgenden beiden sind äquivalent
imTricky && doMagic();

if(imTricky) {
    doMagic();
}

Offensichtlich ist Letzteres besser. Syntaktische Tricks bringen keinen Nutzen.

  • Konstanten benennen: Wenn es einige spezielle Werte im Code gibt, ist es am besten, sie zu benennen. var PURPOSE_OF_LIFE = 42;
  • Regeln aufstellen: Es ist am besten, konsistente Namensregeln zu befolgen. Auf diese Weise können Leser die Bedeutung verschiedener Dinge richtig erraten, indem sie sich auf anderen Code beziehen.

Quelle: http://www.ido321.com/1360.html