Einführung
In der vorherigen Übung haben wir gesehen, dass es in Go zwei Möglichkeiten gibt, Kommentare zu schreiben: einzeilige Kommentare, denen // vorangestellt ist, und mehrzeilige Kommentarblöcke, die mit /* und */ umschlossen werden.
Dokumentationskommentare
In Go spielen Kommentare eine wichtige Rolle beim Dokumentieren von Code.
Sie werden von godoc verwendet, das diese Kommentare extrahiert, um Dokumentation über Go-Pakete zu erstellen.
Ein Dokumentationskommentar sollte ein vollständiger Satz sein, der mit dem Namen des beschriebenen Elements beginnt und mit einem Punkt endet.
Kommentare sollten sowohl vor Paketen als auch vor exportierten Bezeichnern stehen, zum Beispiel vor exportierten Funktionen, Methoden, Paketvariablen, Konstanten und Structs, über die du in den nächsten Übungen mehr erfährst.
Eine Variable auf Paketebene kann so aussehen:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
Paketkommentare
Paketkommentare sollten direkt vor einer Paketklausel (package x) geschrieben werden und mit Package x ... beginnen, etwa so:
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
Funktionskommentare
Ein Funktionskommentar sollte direkt vor der Funktionsdeklaration geschrieben werden.
Er sollte ein vollständiger Satz sein, der mit dem Funktionsnamen beginnt.
Ein exportierter Kommentar für die Funktion Calculate sollte zum Beispiel die Form Calculate ... haben.
Außerdem sollte er erklären, welche Argumente die Funktion entgegennimmt, was sie damit macht und was ihre Rückgabewerte bedeuten, und mit einem Punkt enden:
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
Anleitung
Goblinocus ist ein Land, das seine Wettervorhersage sehr ernst nimmt.
Weil du bekannt dafür bist, verantwortungsbewusst und versiert zu arbeiten, baten sie dich, ein Programm zu schreiben, das die aktuelle Wetterlage in verschiedenen Städten von Goblinocus vorhersagen kann.
Du hattest damals keine Zeit und hast stattdessen jemanden aus deinem Freundeskreis gebeten, die Arbeit zu übernehmen.
Nach einer Weile meldete sich der Präsident von Goblinocus bei dir und sagte, er verstehe den Code dieser Person nicht.
Als du den Code durchgehst, stellst du fest: Die Person hat nicht wie eine verantwortungsbewusste Programmiererin oder ein verantwortungsbewusster Programmierer gehandelt, und im Code stehen keine Kommentare.
Du fühlst dich verpflichtet, das Programm so zu erklären, dass auch Goblins es verstehen.
1. Dokumentiere das Paket weather
Da Goblins nicht so schlau sind wie du, haben sie vergessen, was das Paket für sie tun soll.
Schreib bitte einen Kommentar für package weather, der den Inhalt beschreibt.
Der Paketkommentar sollte das Paket vorstellen und Informationen liefern, die für das Paket als Ganzes relevant sind.
2. Dokumentiere die Variablen CurrentCondition und CurrentLocation
Der Präsident von Goblinocus ist ein wenig paranoid und befürchtet, dass unkommentierte Variablen dazu benutzt werden, sein Land zu zerstören.
Erkläre bitte die Verwendung der Paketvariablen CurrentCondition und CurrentLocation und beruhige den Präsidenten.
Das sollte jedem Nutzer des Pakets sagen, welche Informationen die Variablen speichern und was er damit anfangen kann.
3. Dokumentiere die Funktion Forecast()
Die für die Vorhersage zuständigen Mitarbeiter in Goblinocus möchten wissen, was die Funktion Forecast() macht (aber sag ihnen nicht, wie sie es macht, denn leider würden sie dadurch nur noch verwirrter).
Schreib bitte einen Kommentar für diese Funktion, der beschreibt, was die Funktion tut, aber nicht, wie sie es tut.
Lernübung
