Kaffeepause Nr. 79. 10 Fehler, die Java-Entwickler machen und die ihnen den Erfolg verwehren. Ein Leitfaden für Entwickler zum Schreiben aussagekräftiger Codekommentare

10 Fehler, die Java-Entwickler machen und die ihren Erfolg beeinträchtigen

Quelle: Dev.to Basierend auf meiner Erfahrung habe ich eine Liste mit 10 Fehlern zusammengestellt, die Entwickler machen und die sie am Erfolg hindern:

1. Schreiben Sie keine Unit-Tests

Entwickler, die keine Unit-Tests schreiben, machen mehr Fehler in ihrem Code. Dies führt zu Produktinstabilität und Unzufriedenheit der Kunden.

2. Sie überprüfen den Code nicht manuell

Selbst wenn Sie Ihren Code vollständig mit Unit-Tests abdecken, besteht immer noch die Möglichkeit, dass Sie etwas übersehen haben. Es wird immer empfohlen, Ihren Code manuell zu testen, bevor Sie ihn zur Überprüfung einreichen. So können Sie Fehler bereits im Entwicklungsstadium erkennen.

3. Sie denken: „Das wird nie passieren.“

Entwickler machen beim Schreiben von neuem Code oft Fehler, weil sie denken, dass bestimmte Szenarien nie eintreten werden. Am Ende stellt sich heraus, dass sie falsch liegen. Bewältigen Sie alle Szenarien, in denen Code ausgeführt werden kann. Defensive Programmiermethoden helfen Ihnen dabei.

4. Erhalten Sie kein Feedback

Holen Sie regelmäßig Feedback von anderen Entwicklern und Benutzern ein. Teilen Sie Ihre Meinung mit Ihren Kollegen.

5. Sie überprüfen nicht die Funktionalität des Codes.

Oftmals schreiben Entwickler ihren Code, prüfen aber nicht dessen Funktionalität. Wenn der Code in die Produktion gelangt, entstehen daher verschiedene Probleme.

6. Schreiben Sie langen Prozedurcode

Es ist sehr einfach, lange Methoden mit viel Logik zu schreiben. Auf diese Weise implementieren Programmierer an vielen Stellen dieselbe Logik. Projekte mit einer erheblichen Anzahl kleiner Methoden ermöglichen eine wesentlich bessere Wiederverwendung des Codes und sind viel einfacher zu warten.

7. Sie kennen die Werkzeuge nicht

Werkzeuge sind eine Verlängerung Ihrer Hände. Je besser Sie sie kennen, desto produktiver werden Sie sein. Sie sollten mit der von Ihnen verwendeten IDE bestens vertraut sein. Lernen Sie Schnellbefehle, es gibt immer Befehle, die Ihnen helfen, noch produktiver zu sein. In IntelliJ IDEA sind dies Sonar Lint, Spot Bugs und Code Metrics.

8. Ignorieren Sie Probleme im Code

Die Entwickler, die an den erfolgreichsten Produkten arbeiten, ändern ständig den Code. Scheuen Sie sich nicht, Ihren Code umzugestalten. Wenn Ihr Code einem Unit-Test unterzogen wird, ist die Wahrscheinlichkeit einer Regression gering. Entwickler ignorieren häufig problematischen Code. Als Entwickler sind Sie dafür verantwortlich, die Anwendung in gutem Zustand zu halten. Beheben Sie daher alle festgestellten Probleme.

9. Sie programmieren, ohne sich der Konsequenzen bewusst zu sein.

Entwickler sollten NIEMALS Änderungen am Code vornehmen und ihn in die Produktion freigeben, ohne die Konsequenzen zu verstehen. Der Code kann für die angegebenen Testwerte korrekte Ergebnisse liefern. Es kann jedoch vorkommen, dass dies zu unvorhersehbaren Ergebnissen und ernsthaften Problemen führt. „Unvorhersehbare“ Codierung kommt häufig vor, wenn Entwickler Funktionen aus Bibliotheken verwenden, die sie nicht vollständig verstehen. Dies kann auch passieren, wenn ein Entwickler ein Problem behebt, ohne die Lösung zu verstehen.

10. Bitten Sie nicht um Hilfe

Entwickler sind keine sehr geselligen Menschen. Sie lösen Probleme gerne selbst. Aber die Ära, in der ein Entwickler ein Produkt von Anfang bis Ende selbst erstellt, ist vorbei. Softwareentwicklung ist eine Teamaktivität. Wenn beim Programmieren ein Problem auftritt, versuchen Sie, es selbst zu lösen. Aber verschwenden Sie nicht zu viel Zeit, wenn Sie keine Lösung finden. Es besteht eine hohe Wahrscheinlichkeit, dass einige Ihrer Kollegen bereits auf das gleiche Problem gestoßen sind und die Lösung kennen. Dies spart Zeit und erhöht die Produktivität.

Ein Leitfaden für Entwickler zum Schreiben aussagekräftiger Codekommentare

Quelle: Stepsize In den meisten Fällen sind Sie nicht der Einzige, der an demselben Projekt oder derselben Codebasis arbeitet. Das bedeutet, dass andere Personen Ihren Code verstehen müssen. Dies gilt auch für Codekommentare. Entwickler schreiben oft „schnelle und schmutzige“ Kommentare ohne viel Kontext, sodass ihre Kollegen nicht wissen, was der Autor sagen wollte. Dies ist eine schlechte Praxis und schafft mehr Verwirrung als Klarheit. Klare Codekommentare helfen anderen Entwicklern. Ein Codekommentar, der eine Funktion, ihre Begründung, Eingabe und Ausgabe beschreibt, beschleunigt den Lernprozess für andere Entwickler. Andererseits führen uns Codekommentare zu der Frage: Lohnt es sich, sie zu schreiben? Eine bedeutende Gruppe von Entwicklern lehnt das Schreiben von Codekommentaren ab. Der Grund liegt darin, dass der Code ihrer Meinung nach selbsterklärend ist. Wenn ein anderer Entwickler den Zweck Ihres Codes nicht erkennen kann, indem er ihn sich ansieht, dann handelt es sich um schlechten Code. Vielleicht stimmt das. Denken Sie jedoch an den geringen Aufwand, der zum Auskommentieren von Code erforderlich ist, und an die potenziellen Vorteile, die es mit sich bringt. Codekommentare sind wichtig, um den Onboarding-Prozess für jeden Entwickler, insbesondere für Junior-Entwickler, zu beschleunigen. Schauen wir uns die verschiedenen Arten von Codekommentaren an.

1. Kommentare zur Dokumentation.

Der Hauptzweck solcher Kommentare besteht darin, den Zweck einer Datei oder Komponente schnell zu verdeutlichen. Anstatt den gesamten Code einer Komponente zu lesen, um zu verstehen, was sie tut, können Sie oben in der „Index“-Datei einen Codekommentar hinzufügen. Dies hilft zu erklären, was diese Komponente tut. Ich bin kein großer Fan dieser Art von Kommentaren, weil sie den Code etwas unübersichtlich machen. Ich denke, diese Art von Architekturkommentaren sollten in Ihrer internen Dokumentation enthalten sein, wo Sie die Architektur Ihres Projekts zentral verwalten und diskutieren können. Open-Source-Projekte brauchen sie jedoch wirklich.

2. Kommentare zu Funktionen.

Dies ist die nützlichste Art von Kommentar. Sie beschreiben den Zweck der Funktion, ihre Parameter und ihre Ausgabe.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Logische Kommentare.

Dabei handelt es sich um Kommentare innerhalb von Funktionen zur Verdeutlichung komplexer Codepfade. Wie Sie vielleicht schon vermutet haben, weist das Vorhandensein solcher Kommentare darauf hin, dass Ihr Code zu komplex ist. Darüber hinaus enthalten logische Kommentare häufig zu viele detaillierte Informationen. Der Detaillierungsgrad führt zu mehr Chaos und verringert die Lesbarkeit Ihres Codes. Hier ist ein Beispiel für einen zu detaillierten Codekommentar.

let date = new Date(); // store today's date to calculate the elapsed time

Code-Kommentierung: 4 Best Practices für das Kommentieren

1. Verwenden Sie Codeanmerkungen oder Tags

Viele Programmiersprachen definieren Standards für das Kommentieren von Code. Java verwendet Javadoc , während JavaScript das Codekommentarsystem JSDoc verwendet , das von vielen Dokumentationstools unterstützt wird. Für Funktionen müssen Sie die folgenden Code-Tags einbinden:

• @desc – Beschreibung Ihrer Funktion
• @param – alle Eingabeparameter, die die Funktion akzeptiert. Geben Sie unbedingt Eingabetypen an.
• @returns – zurückgegebene Ausgabe. Geben Sie unbedingt den Ausgabetyp an.
• @throws ist die Art von Fehler, die die Funktion auslösen kann.
• @example – ein oder mehrere Beispiele, die die Eingabe und die erwartete Ausgabe zeigen.

Hier ist ein Beispiel -Lodash-Code für die Chunk- Funktion .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Erklären Sie den Grund für Ihr Handeln

Viele Entwickler verwenden Kommentare, um zu beschreiben, was ihr Code tut. Geben Sie dabei unbedingt an, warum Sie eine bestimmte Funktion oder Komponente erstellt haben. Diese Informationen werden Kontext genannt. Der Kontext ist wichtig, um Entwicklern mehr Informationen über die Designentscheidungen hinter einem Feature oder einer Komponente zu geben. Der Kontext ist entscheidend, wenn andere Entwickler Änderungen an Ihrer Funktion oder Komponente vornehmen möchten. Unten sehen Sie ein schlechtes Beispiel für das Kommentieren von Code ohne Kontext.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. Verlinken Sie nicht auf andere Dokumente oder Kommentare

Es wird nicht empfohlen, auf andere Codekommentare oder interne Dokumente zu verlinken, die eine Funktion oder Komponente erläutern.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Schreiben Sie beim Codieren Kommentare

Das mag offensichtlich erscheinen, aber viele Entwickler (ich eingeschlossen) vernachlässigen diese Regel. Es ist schlecht, Kommentare für später aufzubewahren, da Sie möglicherweise einen Teil der von Ihnen geschriebenen Logik vergessen, was zu Codekommentaren von geringerer Qualität führt. Dies gilt insbesondere dann, wenn Sie mehrere Tage lang an derselben Pull-Anfrage gearbeitet haben. Es ist besser, Kommentare zu schreiben, wenn Sie gerade eine Funktion oder ein Modul fertiggestellt haben. Denken Sie daran, Codekommentare so kurz wie möglich zu halten. Sie müssen nicht mehr Zeit mit dem Schreiben von Kommentaren verbringen als mit dem Schreiben des Codes selbst.