Seite 2: Willkommen im Projekt

Wenn Entwickler in einem neuen Projekt starten, benötigen sie ein paar Eckdaten: Wie heißt das Projekt? Worum geht es? Wo finde ich weitere Informationen? Im AsciiDoc-Format sieht es wie folgt aus:

= Ultimatives App-Projekt

Mit diesem Projekt machen wir unsere Kundinnen und Kunden glücklich!

== Was uns einzigartig macht

- Funktionen, die niemand anderes hat.
- Durchdachte Interaktion für alle und Nutzerinnen und Nutzer.
- ...

== So startest du als Entwickler

Starte die Anwendung im Entwicklungsmodus mit folgenden zwei Kommandos:

  npm install
  npm run dev

== Mehr Informationen

In unserem https://github.com/dummy[GitHub-Repository] findest du unsere Ticket-Verwaltung.

Am Anfang steht der Titel, den ein Gleichheitszeichen (=) einleitet. Zwei Gleichheitszeichen leiten die Überschriften der ersten Ebene ein. Aufzählungen starten mit einem Spiegelstrich. Kommandos auf der Kommandozeile sind etwas eingerückt. Ein Link mit URL und als dargestellter Text steht im letzten Abschnitt.

Dieser Text könnte auch eins zu eins in einer Begrüßungs-E-Mail an neue Entwickler stehen. Als Konvention hat es sich jedoch etabliert, dass ein solcher Text in einer Datei README.adoc im Wurzelverzeichnis eines Quellcode-Repositorys steht. .adoc ist dabei die übliche Dateiendung für AsciiDoc-Dateien. Versionsverwaltungen wie GitHub oder GitLab erkennen README als die Datei, die sie auf der Startseite eines Repositorys automatisch anzeigen. Dabei zeigen sie nicht die Textversion an, sondern formatieren sie ähnlich wie unten dargestellt mit hervorgehobenen Überschriften, Aufzählungen und Links.

Die Entwicklerdokumentation

Wenn Entwickler in einem neuen Projekt anfangen, ist ein README.adoc ein erster guter Start. Danach benötigen sie weitere Informationen mit Codebeispielen. Bei der Navigation in einem solchen Dokument hilft ein Inhaltsverzeichnis. Querverweise im Dokument erleichtern selektives, nichtlineares Lesen im Dokument. Hier ein Beispiel aus einem Entwicklungshandbuch. Das Attribut toc zu Beginn des Dokuments generiert ein automatisches Inhaltsverzeichnis:

= Entwicklungshandbuch
Vorname Nachname <autor@asciidoctor.org>
1.0, 31.10.2019: Halloween Release
:toc-title: Inhaltsverzeichnis
:toc:
:icons: font

// Bitte den Abschnitten IDs geben, um sie später referenzieren zu können!
[[sec:code-conventions]]
== Code-Konventionen

Hier eine kurze Einführung in unsere Code-Konventionen.

.Beispielcode
[source,java]
----
/**
 * Beschreibung, warum diese Methode existiert. <1>
 */
public int calculatePowerOfTwo(int num) {
  return num * num; // <2>
}
----
<1> Wir dokumentieren unsere Methoden, es sei denn, es sind einfache Getter- und Setter.
<2> Du kannst den Wert direkt zurückgeben, ohne ihn vorher in eine Zwischenvariable zu schreiben.

[[sec:code-review]]
== Code-Review

. Prüfe die <<sec:code-conventions>>!
. Gibt es Kommentare, die das "`Warum`" beschreiben?
. Gibt es einen Test, der neue Code-Teile abdeckt?

NOTE: Code-Reviews sind unsere erste Verteidigungslinie gegen Bugs in Produktion!

Im Listing des Handbuchs ist der annotierte Quellcode sichtbar. Die einzelnen Nummern im Quellcode verweisen auf kurze Hinweise darunter. Ein Hinweis ist mit NOTE: hervorgehoben.

In eine HTML-Datei konvertiert wird der annotierte Quellcode wie abgebildet dargestellt. Die hervorgehobenen Hinweise stellt die HTML-Ausgabe als Icons dar, da das Attribut icons auf den Wert font gesetzt wurde. Der Quellcode wird durch Syntax-Highlighting lesbarer.

Das vorherige Beispiel enthielt Quellcode, der als Auszug aus einer Datei in das Dokument hineinkopiert wurde. Das kann dazu führen, dass der Quellcode in der Originaldatei angepasst wird, in der Dokumentation jedoch nicht oder nur unvollständig. Dadurch wäre das Codebeispiel veraltet und kompiliert vielleicht nicht mehr. Besser ist es, die Zeilen zu referenzieren statt sie zu kopieren. Hier ein Beispiel zunächst des Quellcodes mit zusätzlichen tags-Kommentaren, dann eingebunden in ein Dokument:

public class Calculator {
    // tag::mymethod[]
    public int calculatePowerOfTwo(int num) {
        return num * num; // <2>
    }
    // end::mymethod[]
}

[source,java,indent=0]
----
include::Calculator.java[tag=mymethod]
----
<2> Du kannst den Wert direkt zurückgeben...

Damit kompilieren die Codebeispiele und sind wie jeder andere Code durch Unit-Tests testbar. Die zusätzliche Option indent=0 passt die Einrückung an und entfernt die führenden Leerzeichen des ausgeschnittenen Codebeispiels. Das ermöglicht Entwicklungshandbücher von hoher Qualität.