Die Worte "selbstdokumentierender Code" sind eine andere Art, "lesbaren Code" zu sagen. Es wird diese Dokumentation oder gute Kommentare nicht ersetzen, aber mit oder ohne sie wird es definitiv Ihr Leben und das Leben Ihrer Kollegen erleichtern.
Schauen wir uns einige wichtige Prinzipien für die Erstellung von selbstdokumentierendem Code an.
Verwenden Sie keine "magischen Zahlen"
Sag mir, was bedeutet diese Zeile?
if (students.length > 23) {
Prüft, ob mehr Schüler als 23 sind? Und was heißt das? Warum genau 23 und nicht 24?
Eine magische Zahl ist eine Zahl ohne Kontext. Sie müssen Zeit und Mühe aufwenden, um diesen Kontext zu verstehen. Vermeiden Sie unnötige Arbeiten und geben Sie der Nummer sofort die Bezeichnung:
const maxClassSize = 23; if (students.length > maxClassSize) {
Versuchen Sie jetzt, den Code zu lesen. Wir überprüfen nicht, ob es mehr Schüler als 23 gibt, sondern, ob es mehr Schüler gibt, als die Klasse beherbergt.
Verwenden Sie eindeutige Namen für Variablen
Ich weiß nicht warum, aber vorher hatte ich ständig Angst, Variablennamen lang zu machen. Das war dumm von mir, da rStuNms und fStuNms im Vergleich zu r awStudentNames und filtersStudentNames schrecklich sind.
Scheint letzteres noch lang zu sein? Denken Sie dann darüber nach: Nach 2 Wochen Urlaub und der Arbeit mit einem anderen Code werden Sie gut die Hälfte der Abkürzungen vergessen. Die Fähigkeit, Variablennamen unterwegs zu lesen, ist die Fähigkeit, Code im Handumdrehen zu lesen:
const fStuNms = stus.map(s => sn)
Ein weiterer guter Tipp ist die Verwendung von Konventionen (Namenskonventionen). Wenn die Variable boolesch ist, beginnen Sie ihren Namen mit is oder has ( isEnrolled: true ). Wenn die Variable ein Array ist, verwenden Sie den Plural ( Studenten ). Viele Zahlen müssen mit min oder max beginnen . Und Funktionsnamen müssen ein Verb enthalten, z. B. createSchedule oder updateNickname . Apropos Funktionen ...
Schreiben Sie winzige benannte Funktionen
Variablen sind nicht die einzige Möglichkeit, Code zu lesen. Als junger Programmierer habe ich Funktionen nur verwendet, um Codeduplizierungen zu vermeiden . Die wirkliche Offenbarung für mich war, dass es zuallererst Sinn macht, Funktionen zu erstellen, um zu beschreiben, was passiert .
Nehmen Sie sich ein paar Sekunden Zeit, um diesen Code anzusehen und zu sagen, was er bewirkt:
const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(() => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout(() => setIsAlertVisible(false), 2000); }) .then(() => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }); };
Nun mache dasselbe für den Code:
const showSaveAlertFor = (milliseconds) => () => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout( () => setIsAlertVisible(false), milliseconds, ); }; const updateTitleIfNew = () => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }; const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(showSaveAlertFor(2000)) .then(updateTitleIfNew); };
Es scheint, dass es mehr Zeichen gibt, aber wie viel besser lesbar, oder? Alles, was benötigt wurde, war die Aufteilung der logischen Operationen in kleine benannte Funktionen. Darüber hinaus müssen die kleinen Funktionen selbst in den meisten Situationen nicht gelesen werden - dies sind Implementierungsdetails. Um den Code zu verstehen, schauen Sie sich einfach die oberste Funktion an, die aus einer Kette von leicht verständlichen Ereignissen besteht.
Darüber hinaus werden Sie wenig später feststellen, dass solche kleinen Funktionen sehr einfach wiederzuverwenden sind. Die Wiederverwendbarkeit ist eine Folge der besseren Lesbarkeit und nicht umgekehrt.
Fügen Sie nützliche Testbeschreibungen hinzu
Am wenigsten wird wohl von selbst dokumentierten Tests gesprochen, aber vergebens.
Nehmen wir an, wir haben eine Funktion wie diese:
const getDailySchedule = (student, dayOfWeek) => {
Stellen Sie sich vor, es enthält viele verschiedene Vorgänge: Es wird ein Zeitplan für einen Monat erstellt. Wenn heute ein freier Tag ist, wird ein leeres Array zurückgegeben. Wenn der Schüler in zusätzlichen Klassen eingeschrieben ist, fügt er diese am Ende des Tages hinzu usw. Im Allgemeinen haben Sie die Idee verstanden: Die Funktion ist komplex und es wäre schön, den Algorithmus ihrer Arbeit irgendwo in einfachen Worten aufzuschreiben.
Der Versuch, es in einen Kommentar einzufügen, ist eine schlechte Idee: Ein Kommentar wird einmal veraltet sein und nicht die Tatsache, dass er rechtzeitig korrigiert wird. Wissen Sie, wo die Aufzeichnung des Operationsalgorithmus angebracht ist? In Tests:
describe('getDailySchedule ', () => { it(" ", () => { it(' , ', () => { it(' ', () => {
Dies ist die eleganteste Möglichkeit, Code ohne Kommentar im Code zu kommentieren.
Fazit: Lesbarkeit ist wichtiger als Klugheit
Jeder kann Code schreiben, der für ihn selbst verständlich ist, ein guter Entwickler schreibt Code, der für andere verständlich ist . Selten wird etwas Wichtiges von einer einzelnen Person erstellt, was bedeutet, dass früher oder später andere Personen Ihren Code lesen. Aber selbst wenn Sie sicher sind, dass nur Sie über einen Code nachdenken, denken Sie daran, dass Sie heute und in einem Monat unterschiedliche Personen sind, was die Fähigkeit betrifft, sich diesen Code zu merken.