Dart Kommentare

Die Dart-Sprache unterstützt insgesamt drei Kommentararten: Einzeilkommentare, Mehrzeilkommentare und Dokumentationskommentare. Der Compiler ignoriert normalen Text innerhalb von Kommentaren, nur Dokumentationskommentare können zur Erstellung von Codedokumentationen verwendet werden.

Kommentare helfen Entwicklern, den Code, seine Funktionen und Aufgaben nachzuvollziehen. Außerdem lassen sich Codeabschnitte temporär ausblenden, um Programme zu debuggen und Fehler zu suchen.

Mithilfe von Werkzeugen lassen sich aus Dokumentationskommentaren automatische Hilfedokumente zum Code erstellen. Das erleichtert sowohl die eigene Nachschau als auch das Verständnis für andere Entwickler, die Ihren Code nutzen.

Wenn Sie bereits andere Programmiersprachen gelernt haben, verstehen Sie Kommentare schnell. Die Syntax ähnelt stark C, C++, Java, C# und weiteren C-ähnlichen Sprachen.

1. Einzeilkommentar //

1. Beginn mit dem Zeichen //;
2. Aller Inhalt ab // bis zum Zeilenende wird vom Dart-Compiler ignoriert;
3. Gilt nur für die aktuelle Zeile, zeilenübergreifende Nutzung ist nicht möglich.

Beispielcode

void main() {
  // TODO: Zu abstrakter Lama-Begrüßungsfabrik-Klasse refaktorisieren?
  print('Willkommen auf meiner Lama-Farm!');
}
Code-Sprache: JavaScript (javascript)

2. Mehrzeilkommentar /* */

1. Startmarkierung /*, Endmarkierung */;
2. Der gesamte Inhalt zwischen /* und */ wird vom Compiler ignoriert (außer Dokumentationskommentare, siehe unten);
3. Verschachtelte Kommentare werden unterstützt.

Beispielcode

void main() {
  /*
   * Die Lama-Haltung erfordert viel Aufwand, man könnte stattdessen Hühner züchten.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Code-Sprache: Dart (dart)

Im obigen Code ist der gesamte Inhalt innerhalb der geschweiften Klammern auskommentiert, er wird nicht kompiliert und vom Compiler vollständig ignoriert.

3. Dokumentationskommentare

Sie dienen zur Erstellung der offiziellen API-Dokumentation. Andere Entwickler können über diese Dokumente Beschreibungen zu Klassen, Funktionsschnittstellen, Parametern und weiteren Nutzungshinweisen abrufen – vergleichbar mit einer Bedienungsanleitung.

1. Zwei Schreibweisen

• Einzeil-Dokumentationskommentar: Mehrere aufeinanderfolgende Zeilen mit ///, funktioniert wie ein mehrzeiliger Dokumentationskommentar. Beachten Sie die drei Schrägstriche.
• Mehrzeil-Dokumentationskommentar: Beginnt mit /**, endet mit */. Am Anfang steht ein zusätzlicher Sternchen.

2. Zentrale Syntaxregeln

1. Normaler Text in Dokumentationskommentaren wird vom Code-Analysetool ignoriert;
2. Spezielle Syntax: Bezeichner in eckigen Klammern [] ermöglicht Verweise auf Klassen, Methoden, Felder, Top-Level-Variablen, Funktionen und Parameter;
3. Namen in eckigen Klammern werden im lexikalischen Gültigkeitsbereich des kommentierten Codes aufgelöst;
4. Nach Generierung der Dokumentation wird [Bezeichner] automatisch zu einem Hyperlink zur passenden Dokumentation umgewandelt.

Beispielcode

// Einfacher Einzeilkommentar: Definition der Futterklasse
class Food {
  String type;
  // Einzeilkommentar: Anzahl Futterbündel
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
Einfacher Mehrzeilkommentar:
Aufzählung der Bewegungsarten für die Lama-Bewegungsfunktion
Demonstration verschachtelter Kommentare
/* Innerer verschachtelter Kommentar */
*/
enum Activity {
  walk,
  run,
  graze
}

/// Gezähmtes südamerikanisches Kameltier (Lama, wissenschaftlicher Name Lama glama)
///
/// Bereits vor der Kolonialzeit nutzten die Andenvölker Lamas als Fleischlieferant und Lasttier.
///
/// Wie alle Tiere brauchen Lamas Futter: Verwenden Sie Futter vom Typ [Food] und rufen Sie die Methode [feed] auf.
class Llama {
  String? name;

  /// Füttert das Lama mit dem angegebenen [food]
  ///
  /// Ein Lama verbraucht üblicherweise ein Heubündel pro Woche.
  void feed(Food food) {
    // Einzeilkommentar: Ausgabe der Fütterungsinformationen
    print("${name} frisst ${food.baleCount} Bündel ${food.type}");
  }

  /// Lässt das Lama die Aktivität [activity] für [timeLimit] Minuten ausführen
  void exercise(Activity activity, int timeLimit) {
    print("${name} macht ${activity.name} für ${timeLimit} Minuten");
  }
}

void main() {
  // TODO: Erweiterung zur Verwaltung mehrerer Lamas geplant
  Llama larry = Llama();
  larry.name = "Larry";

  // Heufutter erstellen
  Food hay = Food("Heu", 1);
  larry.feed(hay);

  // 20 Minuten Spaziergang für das Lama
  larry.exercise(Activity.walk, 20);
}
Code-Sprache: PHP (php)

Nach Generierung der Dokumentation verweist [feed] auf die Dokumentation der feed-Methode der aktuellen Klasse, [Food] auf die Dokumentation der Food-Klasse.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
Larry frisst 1 Bündel Heu
Larry macht walk für 20 Minuten

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiCode-Sprache: JavaScript (javascript)

Anschließend wird im Projektordner ein Ordner doc erstellt, darin befinden sich die generierten Dokumente

Zugehörige Werkzeuge

1. Dokumentationsgenerator: dart doc Funktion: Analysiert Dart-Quellcode und erstellt automatisch HTML-basierte API-Dokumentation für das Projekt. Auch die offizielle Dart-API-Dokumentation wird mit diesem Tool erstellt.
2. Referenz für Kommentarrichtlinien: Offizieller Leitfaden „Effective Dart: Documentation“ mit standardisierten Strukturen und Schreibstilen für Kommentare.

Zusammenfassung

Vergleichstabelle

Kommentartyp	Startzeichen	Mehrzeilig	Verschachtelbar	Verwendungszweck
Einzeilkommentar	//	Nein, nur eine Zeile	Nein	Kurze Notizen, TODO-Aufgaben im Code
Normaler Mehrzeilkommentar	/* */	Ja, beliebig viele Zeilen	Ja	Große Codeblöcke auskommentieren, lange Erläuterungen
Dokumentationskommentar	/// / /** */	Ja	Nicht empfohlen	API-Beschreibungen für Klassen/Methoden/Variablen, Generierung offizieller Dokumente, Verlinkung von Bezeichnern per []