Wie oft mussten Sie sich in den Code eines anderen vertiefen? Anstelle von zwei Stunden verbringen Sie möglicherweise zwei Tage damit, einfach die Logik des Geschehens zu verstehen. Das Lustige ist, dass für die Person, die den Code geschrieben hat, alles klar und völlig transparent ist. Dies ist nicht verwunderlich, schließlich ist perfekter Code ein sehr vages Konzept, da jeder Entwickler seine eigene Vision von der Welt und auch vom Code hat. Ich war mehr als einmal in der Situation, dass ein Kollege und ich uns denselben Code angesehen haben und unterschiedliche Meinungen über seine Richtigkeit und Sauberkeit hatten.
Kommt Ihnen bekannt vor, nicht wahr? Dennoch gibt es einige bewährte Grundsätze, die eingehalten werden sollten. Am Ende werden sie für Sie von Vorteil sein, denn wenn Sie Ihren Code in dem Zustand belassen, in dem Sie ihn selbst gerne erhalten würden, dann würde die Welt ein wenig glücklicher und sauberer werden. In unserem vorherigen Artikel(oder besser gesagt, ein kleiner Leitfaden) über Codierungsregeln haben wir einen kleinen Eindruck von Empfehlungen zum Schreiben eines Systems als Ganzes und seiner Bestandteile wie Objekte, Schnittstellen, Klassen, Methoden und Variablen bekommen. Im selben Artikel habe ich beiläufig die korrekte Benennung bestimmter Elemente erwähnt. Darüber möchte ich heute sprechen, denn richtige Namen machen den Code um ein Vielfaches leichter lesbar. Wir schließen das Thema korrekter Code mit einigen Überlegungen, kleinen Beispielen für Kommentare im Code und einer Überlegung ab, ob dieser gut oder nicht so gut ist. Nun, fangen wir an.
Richtige Namen
Korrekte Namen verbessern die Lesbarkeit des Codes und verkürzen so die Einarbeitungszeit, da die Verwendung einer Methode viel einfacher ist, wenn der Name ihre Funktionalität grob beschreibt. Alles im Code besteht aus Namen (Variablen, Methoden, Klassen, Objekte, Dateien usw.), daher ist dieser Punkt sehr wichtig, wenn es darum geht, korrekten, sauberen Code zu erstellen. Basierend auf dem oben Gesagten sollte der Name eine Bedeutung vermitteln, zum Beispiel, warum die Variable existiert, was sie tut und wie sie verwendet wird. Ich werde mehr als einmal darauf hinweisen, dass der beste Kommentar für eine Variable darin besteht, ihr einen guten Namen zu geben.
aus der TV-Serie „Sherlock“ (2010-2017)
Benennung von Schnittstellen
Schnittstellen haben normalerweise Namen, die mit einem Großbuchstaben beginnen und in CamelCase geschrieben sind. Beim Schreiben einer Schnittstelle galt es früher als gute Praxis, das Präfix „I“ hinzuzufügen, um sie als Schnittstelle zu kennzeichnen (z. B. IUserService), aber das sieht ziemlich hässlich und ablenkend aus. In solchen Fällen ist es besser, das Präfix (UserService) wegzulassen und „Impl“ als Suffix an den Namen seiner Implementierung hinzuzufügen (z. B. UserServiceImpl). Oder fügen Sie als letzten Ausweg möglicherweise ein „C“-Präfix zum Namen der Implementierung hinzu (z. B. CUserService).Klassennamen
Genau wie Schnittstellen werden Klassennamen großgeschrieben und verwenden CamelCase. Es spielt keine Rolle, ob uns eine Zombie-Apokalypse bevorsteht, es spielt keine Rolle, ob das Ende nahe ist – niemals, niemals, niemals sollte der Name einer Klasse ein Verb sein! Klassen- und Objektnamen müssen Substantive oder zusammengesetzte Substantive sein (UserController, UserDetails, UserAccount usw.). Sie sollten die Abkürzung der Anwendung nicht an das Ende des Namens jeder Klasse anhängen, da dies die Komplexität nur unnötig erhöht. Wenn wir beispielsweise eine Anwendung zur Migration von Benutzerdaten haben, fügen Sie bitte nicht „UDM“ zu jeder Klasse hinzu, also UDMUserDetails, UDMUserAccount, UDMUserController.Methodennamen
Normalerweise beginnen Methodennamen mit einem Kleinbuchstaben, sie verwenden jedoch auch die Kamel-Schreibweise (camelCase). Oben haben wir gesagt, dass Klassennamen niemals Verben sein sollten. Hier ist die Situation genau umgekehrt: Die Namen der Methoden sollten Verben oder Verbphrasen sein: findUserById, findAllUsers, createUser usw. Verwenden Sie beim Erstellen einer Methode (sowie von Variablen und Klassen) eine einheitliche Namenskonvention, um Verwirrung zu vermeiden. Um beispielsweise einen Benutzer zu finden, könnte eine Methode getUserById oder findUserById heißen. Und noch etwas: Verwenden Sie keinen Humor in den Namen der Methoden, da andere den Witz möglicherweise nicht verstehen. Infolgedessen verstehen sie möglicherweise nicht, was die Methode bewirkt.Variablennamen
In den meisten Fällen beginnen Variablennamen mit einem Kleinbuchstaben und verwenden auch „camelCase“, außer wenn die Variable eine globale Konstante ist. In solchen Fällen werden alle Buchstaben des Namens in Großbuchstaben geschrieben und die Wörter werden durch einen Unterstrich („_“) getrennt. Der Einfachheit halber können Sie beim Benennen von Variablen einen aussagekräftigen Kontext verwenden. Mit anderen Worten, wenn eine Variable als Teil von etwas Größerem existiert, zum Beispiel „Vorname“, „Nachname“ oder „Status“. In solchen Fällen können Sie ein Präfix hinzufügen, das das Objekt angibt, zu dem diese Variable gehört. Zum Beispiel: userFirstName, userLastName, userStatus. Sie sollten auch ähnliche Namen für Variablen vermeiden, wenn diese völlig unterschiedliche Bedeutungen haben. Hier sind einige häufig vorkommende Antonyme, die in Variablennamen verwendet werden:
- Anfang/Ende
- erster/letzter
- gesperrt/entsperrt
- Minimal Maximal
- weiter zurück
- alt neu
- geöffnet/geschlossen
- sichtbar/unsichtbar
- Quellenziel
- Zielort
- oben unten
Kurze Variablennamen
Wenn wir Variablen wie x oder n oder ähnliches haben, erkennen wir nicht sofort die Absicht der Person, die den Code geschrieben hat. Es ist nicht offensichtlich, was n tut. Um das herauszufinden, bedarf es sorgfältigerer Überlegung (und das bedeutet Zeit, Zeit, Zeit). Angenommen, wir haben ein Feld, das die ID des verantwortlichen Benutzers darstellt. Anstelle eines Variablennamens wie x oder einfach id nennen wir diese Variable „responsibleUserId“, was die Lesbarkeit und den Informationsgehalt sofort verbessert. Allerdings haben kurze Namen wie n ihren Platz als lokale Variablen in kleinen Methoden, bei denen der Codeblock, der diese Variable beinhaltet, nur ein paar Zeilen lang ist und der Methodenname perfekt beschreibt, was dort passiert. Wenn ein Entwickler eine solche Variable sieht, versteht er, dass sie von untergeordneter Bedeutung ist und einen sehr begrenzten Umfang hat. Daher ist der Gültigkeitsbereich in gewisser Weise von der Länge eines Variablennamens abhängig: Je länger der Name, desto globaler ist die Variable und umgekehrt. Als Beispiel ist hier eine Methode, um den zuletzt gespeicherten Benutzer nach Datum zu finden:
public User findLastUser() {
return findAllUsers().stream()
.sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
.findFirst()
.orElseThrow(() -> new ResourceNotFoundException("No user exists"));
}
Optimale Länge
Weiter geht es mit dem Thema Namenslänge. Die optimale Namenslänge liegt irgendwo zwischen n und MaximumNumberOfUsersInTheCurrentGroup. Mit anderen Worten: Kurznamen mangelt es an Bedeutung, zu lange Namen verlängern das Programm, ohne die Lesbarkeit zu verbessern, und wir sind einfach zu faul, sie jedes Mal zu schreiben. Abgesehen von dem oben beschriebenen Fall für Variablen mit einem Kurznamen wie n sollten Sie sich an eine Länge von ca. 8-16 Zeichen halten. Dies ist keine strenge Regel, sondern nur eine Richtlinie.Kleine Unterschiede
Ich kann nicht umhin, subtile Unterschiede in den Namen zu erwähnen. Dies ist auch eine schlechte Praxis, da diese Unterschiede einfach verwirrend sein können oder es erfordert, viel zusätzliche Zeit aufzuwenden, um sie zu bemerken. Beispielsweise ist der Unterschied zwischen InvalidDataAccessApiUsageException und InvalidDataAccessResourceUsageException auf den ersten Blick schwer zu erkennen. Auch bei der Verwendung von Kleinbuchstaben L und O kann es häufig zu Verwirrung kommen, da diese leicht mit 1 und 0 verwechselt werden können. Bei manchen Schriftarten ist der Unterschied deutlicher, bei manchen weniger.Die Bedeutung
Wir müssen Namen aussagekräftig machen, aber keine Mehrdeutigkeit durch Synonyme schaffen, da beispielsweise UserData und UserInfo tatsächlich dieselbe Bedeutung haben. In diesem Fall müssten wir tiefer in den Code eintauchen, um zu verstehen, welches bestimmte Objekt wir benötigen. Vermeiden Sie Wörter, die keine hilfreichen Informationen vermitteln. Warum brauchen wir beispielsweise in „firstNameString“ das Wort „String“? Könnte das wirklich ein Date-Objekt sein? Natürlich nicht. Daher verwenden wir einfach „firstName“. Ich möchte auch boolesche Variablen erwähnen. Nehmen Sie als Beispiel einen booleschen Wert mit dem Namen flagDeleted. Das Wort Flagge hat keine Bedeutung. Es ist vernünftiger, es isDeleted zu nennen.Desinformation
Ich möchte auch ein paar Worte zu falschen Namenskonventionen sagen. Nehmen wir an, wir haben eine Variable namens userActivityList, aber statt einer Liste ist dieses Objekt ein anderer Containertyp oder ein benutzerdefiniertes Speicherobjekt. Dies könnte den durchschnittlichen Programmierer verwirren: Es ist besser, es so etwas wie „userActivityGroup“ oder „userActivities“ zu nennen.Suchen
Einer der Nachteile von kurzen und einfachen Namen besteht darin, dass sie in großen Codemengen schwer zu finden sind. Was wäre leichter zu finden: „name“ oder „NAME_FOR_DEFAULT_USER“? Die zweite Option natürlich. Wir sollten häufig vorkommende Wörter (Buchstaben) in Namen vermeiden, da diese nur die Anzahl der übereinstimmenden Dateien während einer Suche erhöhen, was nicht gut ist. Ich möchte Sie daran erinnern, dass Programmierer mehr Zeit damit verbringen, Code zu lesen als ihn zu schreiben. Seien Sie also klug bei der Benennung der Elemente Ihrer Anwendung. Was aber, wenn ein guter Name einfach nicht gefunden werden kann? Was passiert, wenn der Name einer Methode ihre Funktionalität nicht gut beschreibt? Hier kommen Kommentare auf die Bühne.Kommentare
Es gibt nichts Besseres als einen sachdienlichen Kommentar, aber nichts verstopft ein Modul so sehr wie leere, veraltete oder falsche Kommentare. Sie können ein zweischneidiges Schwert sein, nicht wahr? Dennoch sollten Sie Kommentare nicht als eindeutig gut, sondern als geringeres Übel betrachten. Schließlich ist ein Kommentar im Wesentlichen eine Möglichkeit, Gedanken zu kompensieren, die im Code nicht klar zum Ausdruck kommen. Wir nutzen sie zum Beispiel, um die Essenz einer Methode irgendwie zu vermitteln, wenn sich die Methode selbst als zu verwirrend herausstellt. In dieser Situation ist es besser, den Code korrekt umzugestalten, als beschreibende Notizen zu schreiben. Je älter der Kommentar, desto schlechter ist der Kommentar, da der Code tendenziell wächst und sich weiterentwickelt, die Kommentare jedoch gleich bleiben können. Je mehr Zeit seit der Erstellung eines Kommentars vergangen ist, desto fragwürdiger kann er sein. Ungenaue Kommentare sind viel schlimmer als gar keine Kommentare, weil sie verwirrend und täuschend sind und falsche Erwartungen wecken. Und selbst wenn wir sehr kniffligen Code haben, sollten wir ihn umschreiben, anstatt ihn zu kommentieren.
Arten von Kommentaren
-
Rechtliche Kommentare – Kommentare am Anfang jeder Quelldatei aus rechtlichen Gründen, zum Beispiel:
* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. -
Informative Kommentare – Kommentare, die eine Erläuterung des Codes darstellen (zusätzliche Informationen bereitstellen oder die Absicht eines bestimmten Codeabschnitts erläutern).
Zum Beispiel:
/* * Combines the user from the database with the one passed for updating * When a field in requestUser is empty, it is filled with old data from foundUser */ private User mergeUser(User requestUser, User foundUser) { return new User( foundUser.getId(), requestUser.getFirstName() == null ? requestUser.getFirstName() : foundUser.getFirstName(), requestUser.getMiddleName() == null ? requestUser.getMiddleName() : foundUser.getMiddleName(), requestUser.getLastName() == null ? requestUser.getLastName() : foundUser.getLastName(), requestUser.getAge() == null ? requestUser.getAge() : foundUser.getAge() ); }In diesem Fall kann auf Kommentare verzichtet werden, da sich der Name der Methode und ihre Parameter, gepaart mit einer sehr transparenten Funktionalität, gut beschreiben lassen.
-
Warnkommentare – Kommentar, der andere Entwickler vor den unerwünschten Folgen einer Aktion warnen soll (z. B. davor, warum ein Test als @Ignore markiert wurde):
// Takes too long to run // Don't run if you don't have a lot of time @Ignore @Test public void someIntegrationTest() { …… } -
TODO – Kommentare, die einen Hinweis auf etwas darstellen, das in der Zukunft erledigt werden muss, aber aus irgendeinem Grund jetzt nicht erledigt werden kann. Dies ist eine gute Vorgehensweise, aber solche Kommentare sollten regelmäßig überprüft werden, um irrelevante Kommentare zu entfernen und Unordnung zu vermeiden.
Ein Beispiel wäre:
// TODO: Add a check for the current user ID (when the security context is created) @Override public Resource downloadFile(File file) { return fileManager.download(file); }Hier beachten wir die Tatsache, dass wir einen Vergleich des Benutzers hinzufügen müssen, der den Download-Vorgang durchführt (dessen ID wir aus dem Sicherheitskontext extrahieren), mit dem Benutzer, der den Speichervorgang durchgeführt hat.
-
Bekräftigende Kommentare – Kommentare, die die Bedeutung eines Umstands hervorheben, der auf den ersten Blick unbedeutend erscheinen mag.
Betrachten Sie als Beispiel einen Teil einer Methode, der eine Testdatenbank mit einigen Skripten füllt:
Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8) .trim() .split(";")) .forEach(jdbcTemplate::update); // The trim() call is very important. It removes possible spaces at the end of the script // so that when we read and split into separate requests, we don't end up with empty ones -
Javadoc-Kommentare – Kommentare, die die API für bestimmte Funktionen beschreiben. Es gibt wahrscheinlich die nützlichsten Kommentare, da es viel einfacher ist, mit der dokumentierten API zu arbeiten. Allerdings können sie wie jede andere Art von Kommentar auch veraltet sein. Vergessen Sie also nie, dass der Hauptbeitrag zur Dokumentation nicht durch Kommentare, sondern durch guten Code geleistet wird.
Hier ist ein Beispiel für eine recht gängige Methode zum Aktualisieren eines Benutzers:
/** * Updates the passed fields for a user based on its id. * * @param id id of the user to be updated * @param user user with populated fields for updating * @return updated user */ User update(Long id, User user);
Schlechte Kommentare
-
Murmelnder Kommentar – Kommentare, die normalerweise in Eile geschrieben werden und deren Bedeutung nur für den Entwickler verständlich ist, der sie geschrieben hat, da nur er oder sie die nuancierte Situation wahrnimmt, auf die sich der Kommentar bezieht.
Betrachten Sie dieses Beispiel:
public void configureSomeSystem() { try{ String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE); FileInputStream stream = new FileInputStream(configPath); } catch (FileNotFoundException e) { // If there is no configuration file, the default configuration is loaded } }Wer lädt diese Einstellungen? Wurden sie bereits geladen? Soll diese Methode Ausnahmen abfangen und Standardeinstellungen laden? Es stellen sich zu viele Fragen, die nur durch eine tiefergehende Untersuchung anderer Teile des Systems beantwortet werden können.
- Redundante Kommentare – Kommentare, die keine semantische Last tragen, da das Geschehen in einem bestimmten Abschnitt des Codes völlig klar ist. Mit anderen Worten: Der Kommentar ist nicht einfacher zu lesen als der Code.
Sehen wir uns ein Beispiel an:
public class JdbcConnection{ public class JdbcConnection{ /** * The logger associated with the current class */ private Logger log = Logger.getLogger(JdbcConnection.class.getName()); /** * Creates and returns a connection using the input parameters */ public static Connection buildConnection(String url, String login, String password, String driver) throws Exception { Class.forName(driver); connection = DriverManager.getConnection(url, login, password); log.info("Created connection with db"); return connection; }Was ist der Sinn solcher Kommentare? Alles, was sie erklären, ist bereits vollkommen klar.
-
Unzuverlässige Kommentare – Kommentare, die unwahr und nur irreführend sind (Desinformation). Hier ist zum Beispiel einer.
/** * Helper method. Closes the connection with the scanner if isNotUsing is true */ private void scanClose(Scanner scan, boolean isNotUsing) throws Exception { if (!isNotUsing) { throw new Exception("The scanner is still in use"); } scan.close(); }Was ist an diesem Kommentar falsch? Dass es uns ein wenig belügt, dass die Verbindung geschlossen wird, wenn isNotUsing falsch ist, nicht umgekehrt, wie uns der Kommentar mitteilt.
-
Obligatorische Kommentare – Kommentare, die als obligatorisch angesehen werden (z. B. Javadoc-Kommentare), sich aber tatsächlich manchmal übermäßig anhäufen und unzuverlässig und unnötig sind (Sie müssen darüber nachdenken, ob diese Kommentare tatsächlich benötigt werden).
Beispiel:
/**
* Create a user based on the parameters
* @param firstName first name of the created user
* @param middleName middle name of the created user
* @param lastName last name of the created user
* @param age age of the created user
* @param address address of the created user
* @return user that was created
*/
User createNewUser(String firstName, String middleName, String lastName, String age, String address);
Könnten Sie ohne diese Kommentare verstehen, was die Methode macht? Höchstwahrscheinlich ja, daher werden Kommentare hier sinnlos.
Protokollkommentare – Kommentare, die manchmal bei jeder Bearbeitung am Anfang eines Moduls hinzugefügt werden (so etwas wie ein Änderungsprotokoll).
/**
* Records kept since January 9, 2020;
**********************************************************************
* 9 Jan 2020: Providing a database connection using JDBC Connection;
* 15 Jan 2020: Adding DAO-level interfaces for working with the database;
* 23 Jan 2020: Adding integration tests for the database;
* 28 Jan 2020: Implementation of DAO-level interfaces;
* 1 Feb 2020: Development of interfaces for services,
* in accordance with the requirements specified in user stories;
* 16 Feb 2020: Implementation of service interfaces
* (implementation of business logic related to the work of the database);
* 25 Feb 2020: Adding tests for services;
* 8 Mar 2020: Celebration of International Women's Day (Terry is drunk again);
* 21 Mar 2020: Refactoring the service layer;
*/
Dieser Ansatz war einst gerechtfertigt, aber mit dem Aufkommen von Versionskontrollsystemen (z. B. Git) wurde er zu einer unnötigen Unordnung und Komplikation des Codes.
Autorenkommentare – Kommentare, deren Zweck darin besteht, die Person anzugeben, die den Code geschrieben hat, damit Sie mit ihr Kontakt aufnehmen und besprechen können, wie, was und warum, z. B.:
* @author Bender Bending
Auch hier merken sich Versionskontrollsysteme genau, wer wann Code hinzugefügt hat, sodass dieser Ansatz überflüssig ist.
Auskommentierter Code – Code, der aus dem einen oder anderen Grund auskommentiert wurde. Dies ist eine der schlimmsten Angewohnheiten, denn was passiert, ist, dass man etwas auskommentiert und vergisst, und dann haben andere Entwickler einfach nicht den Mut, es zu löschen (was ist, wenn es schließlich etwas Wertvolles ist?).
// public void someMethod(SomeObject obj) {
// .....
// }
Dadurch sammelt sich auskommentierter Code wie Müll an. Auf keinen Fall sollten Sie einen solchen Code hinterlassen. Wenn Sie es wirklich brauchen, vergessen Sie nicht das Versionskontrollsystem.
Nicht offensichtliche Kommentare – Kommentare, die etwas übermäßig kompliziert beschreiben.
/*
* Start with an array large enough to store
* all the data bytes (plus filter bytes) with a cushion, plus 300 bytes
* for header data
*/
this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];
Ein Kommentar sollte den Code erklären. Es sollte selbst keiner Erklärung bedürfen. Also, was ist hier los? Was sind „Filterbytes“? Was hat es mit diesem „+1“ auf sich? Warum genau 300?
- Verwenden Sie Stile, die leicht zu pflegen sind: Zu ausgefallene und exotische Stile zu pflegen ist lästig und zeitaufwändig.
- Verwenden Sie keine Zeilenendkommentare, die sich auf einzelne Zeilen beziehen: Das Ergebnis ist ein großer Stapel von Kommentaren. Darüber hinaus ist es schwierig, sich für jede Zeile einen sinnvollen Kommentar auszudenken.
- Versuchen Sie beim Verfassen eines Kommentars, die Frage „Warum“ und nicht „Wie“ zu beantworten.
- Vermeiden Sie gekürzte Informationen. Wie ich oben sagte, brauchen wir für einen Kommentar keine Erklärung: Der Kommentar selbst ist die Erklärung.
- Mithilfe von Kommentaren können Sie sich Einheiten und Wertebereiche merken.
- Platzieren Sie Kommentare in der Nähe des Codes, den sie beschreiben.
GO TO FULL VERSION