Web: Kommentare in Java (Lektion 6, Klammer-Kommentare in L14/L20)

CHANGELOG.md

@@ -15,6 +15,7 @@ The format is loosely inspired by Keep a Changelog.
 
 ### Added
 
+- **Web 0.13.38, comments in Java:** lesson 6 has a new step „Kommentare im Code“ after „Jetzt in Java“: single-line `//` and multi-line `/* … */` comments, Java skips them and the structure chart stays the same; Javadoc `/** … */` is only mentioned. The IPO example (with „Im Editor öffnen“) shows the task in a multi-line comment, `// Eingabe`, `// Verarbeitung`, `// Ausgabe`, an explanation after a line, the expected output and a note for next time; plus a fill-in-the-gaps exercise, an Angeberwissen (PL/I 1964, BCPL 1967), a competence, a checklist line and two quiz questions. Lesson 14 marks closing brackets with `} // Ende if` / `} // Ende for`, lesson 20 the class frame with `} // Ende main` / `} // Ende Klasse`. New glossary entry Kommentar and Nachschlagen section „Java › Kommentare“ (de/en/pt).
 - **Web 0.13.36, sequence diagram in lesson 5:** step „Schritt für Schritt“ now shows a sequence as a structure chart: four boxes one below the other (`laenge`, `breite`, `flaeche = laenge * breite`, output 15) with a short caption that each box runs exactly once from top to bottom (de/en/pt).
 - **Web 0.13.35, open Java examples in the editor:** a Java example in a lesson can now carry the button „Im Editor öffnen“. It opens the example in a new tab with Programmieren set to Java, so students can run it, change values and try again; the structure chart builds itself from the code. Lesson 4 step „Text in Java“ (Mia, 14, 1.62) uses it and says how to try it (de/en/pt). For authors: write ```` ```java editor ```` instead of ```` ```java ````; a test checks that every such example parses without errors.
 - **Web 0.13.32, every exercise says where to solve it:** below the title of each exercise card a small label names the area: „Löse diese Übung im Struktogramm.“ or, for `code: java` exercises, „Löse diese Übung in Programmieren.“ The area names are taken from the on-screen headings, so they always match (de/en/pt; applies to all VisuStruct, VisuBot and task-area exercises).

web/lessons/de/06-eingabe-und-ausgabe.md

@@ -13,6 +13,7 @@ kurz: Werte abfragen, Ergebnisse anzeigen und das EVA-Prinzip anwenden.
 - ein Ergebnis zuerst ausrechnen und in einer Variablen speichern, dann diese Variable ausgeben, z. B. `int summe = a + b`, danach `output: summe`
 - aus einem Aufgabentext Eingabe, Verarbeitung und Ausgabe herauslesen
 - in Java mit dem Scanner Zahlen einlesen
+- Kommentare mit `//` und `/* */` schreiben und damit meinen Code einteilen und erklären
 :::
 
 ## Das EVA-Prinzip
@@ -168,6 +169,75 @@ tipp: `int jahre = scanner.nextInt();` liest ein. `int tage = jahre * 365;` rech
 lösung: l06-java-tage-loesung.visustruct
 :::
 
+## Kommentare im Code
+
+Im Code darfst du dir Notizen machen. Sie heißen **Kommentare** (englisch *comments*). Java überspringt sie beim Ausführen, das Programm und das Struktogramm bleiben also gleich. Es gibt zwei Arten:
+
+- `//` macht den Rest der Zeile zum Kommentar. Das ist ein **einzeiliger Kommentar**.
+- `/*` beginnt einen **mehrzeiligen Kommentar**, `*/` beendet ihn. Alles dazwischen gehört zum Kommentar, egal wie viele Zeilen. Die Sternchen am Anfang der Zeilen dazwischen braucht Java nicht, sie sehen nur ordentlich aus.
+
+In fertigen Programmen siehst du manchmal auch `/** … */` mit zwei Sternchen am Anfang. Das ist ein **Javadoc-Kommentar**, aus dem Java eine Beschreibung des Programms erzeugen kann. Für dich reichen `//` und `/* */`.
+
+So sieht das EVA-Beispiel mit Kommentaren aus:
+
+```java editor
+/*
+ * Aufgabe: Das Programm fragt nach zwei Zahlen
+ * und gibt ihre Summe aus.
+ */
+import java.util.Scanner;
+Scanner scanner = new Scanner(System.in);
+
+// Eingabe
+System.out.println("Erste Zahl?");
+int a = scanner.nextInt();
+System.out.println("Zweite Zahl?");
+int b = scanner.nextInt();
+
+// Verarbeitung
+int summe = a + b;      // die beiden Zahlen addieren
+
+// Ausgabe
+System.out.println("Summe: " + summe);      // bei 3 und 4 erwarte ich: Summe: 7
+
+// Nächstes Mal: auch Kommazahlen erlauben
+```
+
+Wofür Kommentare gut sind:
+
+- **Aufgabenstellung:** Oben im mehrzeiligen Kommentar steht, was das Programm können soll.
+- **Einteilung:** `// Eingabe`, `// Verarbeitung` und `// Ausgabe` teilen den Code nach dem EVA-Prinzip ein.
+- **Erklärung:** Ein Kommentar hinter einer Zeile sagt, was dein Algorithmus dort macht.
+- **Erwartung:** Schreib auf, welche Ausgabe du erwartest. Beim Testen vergleichst du dann.
+- **Klammern zuordnen:** Später kommen Blöcke in geschweiften Klammern `{ }` dazu. Dann zeigt z. B. `} // Ende for`, welche Klammer was schließt.
+- **Gedanken festhalten:** Woran musst du denken, wenn du nächstes Mal weiterarbeitest?
+
+Klicke auf **Im Editor öffnen**, ändere einen Kommentar oder schreib einen neuen dazu. Das Struktogramm bleibt gleich, und VisuStruct behält deine Kommentare.
+
+> Schreib nicht hinter jede Zeile einen Kommentar. Erkläre, was dein Algorithmus macht und warum, nicht jedes einzelne Zeichen.
+
+::: angeberwissen
+Beide Arten sind viel älter als Java: `/* … */` stammt aus der Sprache PL/I von 1964, `//` aus BCPL von 1967. Java hat sie über C und C++ geerbt.
+:::
+
+## Lückentext: Kommentare
+
+::: lückentext
+titel: Kommentare ergänzen
+auftrag: Ergänze die Zeichen, damit oben ein mehrzeiliger Kommentar mit der Aufgabe steht und die anderen beiden Notizen einzeilige Kommentare sind.
+```java
+[[/*]]
+ * Aufgabe: Das Programm rechnet Euro in Cent um.
+ [[*/]]
+int euro = 3;
+[[//]] Verarbeitung
+int cent = euro * 100;
+[[//]] Ausgabe, erwartet: 300
+System.out.println(cent);
+```
+erklärung: `/*` öffnet den mehrzeiligen Kommentar und `*/` schließt ihn. `//` gilt nur bis zum Ende der Zeile, darum braucht jede Notiz ihr eigenes `//`.
+:::
+
 ## Lückentext: Eingabe
 
 ::: lückentext
@@ -283,6 +353,7 @@ Schätze dich bei jedem Punkt ehrlich ein: ☂️ noch nicht, ⛅ teilweise, ☀
 - Ich kann ein Ergebnis zuerst ausrechnen und in einer Variablen speichern, dann diese Variable ausgeben, z. B. `int summe = a + b`, danach `output: summe`. → Vorsicht mit + in der Ausgabe
 - Ich kann aus einem Aufgabentext Eingabe, Verarbeitung und Ausgabe herauslesen. → Vom Aufgabentext zum Struktogramm
 - Ich kann in Java mit dem Scanner Zahlen einlesen. → Jetzt in Java
+- Ich kann Kommentare mit `//` und `/* */` schreiben und damit meinen Code einteilen und erklären. → Kommentare im Code
 :::
 
 ## Wissenstest
@@ -328,4 +399,18 @@ Schätze dich bei jedem Punkt ehrlich ein: ☂️ noch nicht, ⛅ teilweise, ☀
 - [ ] Eine Kommazahl
 - [ ] Einen ganzen Satz
 > Für Kommazahlen gibt es `scanner.nextDouble()`, für ein Wort `scanner.next()`.
+
+? Was macht Java mit einem Kommentar?
+→ Kommentare im Code
+- [ ] Es gibt ihn als Text aus.
+- [x] Es überspringt ihn.
+- [ ] Es meldet einen Fehler.
+> Kommentare sind Notizen für Menschen. Das Programm läuft mit und ohne sie genau gleich.
+
+? Wo endet ein Kommentar, der mit `/*` beginnt?
+→ Kommentare im Code
+- [x] Bei `*/`
+- [ ] Am Ende der Zeile
+- [ ] Bei der nächsten Leerzeile
+> Darum kann ein Kommentar mit `/*` über mehrere Zeilen gehen. Ein Kommentar mit `//` endet dagegen am Zeilenende.
 :::

web/lessons/de/14-verschachteln.md

@@ -97,13 +97,15 @@ int anzahl = 0;
 for (int i = 1; i <= n; i++) {
     if (i % 2 == 0) {
         anzahl++;
-    }
-}
+    } // Ende if
+} // Ende for
 System.out.println(anzahl);
 ```
 
 Was im Struktogramm ineinander steckt, steht in Java in geschweiften Klammern ineinander. Jede Ebene ist vier Leerzeichen weiter eingerückt. Ist dein Code durcheinander, hilft der Knopf **Einrücken** oben im Bereich Programmieren.
 
+Bei vielen schließenden Klammern `}` verliert man leicht den Überblick: Welche Klammer gehört zu welchem Block? Ein Kommentar dahinter sagt es dir, z. B. `} // Ende if` und `} // Ende for`. Das hilft dir auch, wenn du später weiterarbeitest.
+
 `anzahl++` ist die Kurzform von `anzahl = anzahl + 1`.
 
 ::: übung l14-java-treppe

web/lessons/de/20-java.md

@@ -98,10 +98,12 @@ public class Einmaleins {
         System.out.println("Welche Reihe?");
         int zahl = scanner.nextInt();
         ...
-    }
-}
+    } // Ende main
+} // Ende Klasse
 ```
 
+Die Kommentare `// Ende main` und `// Ende Klasse` hinter den letzten beiden Klammern sind nicht nötig, aber sehr hilfreich: So siehst du sofort, welche Klammer was schließt, und vergisst keine.
+
 Der Name der Klasse kommt aus dem **Titel** des Diagramms. Die Datei muss genauso heißen, hier also `Einmaleins.java`. Das erledigt **Java speichern …** für dich.
 
 > Der erzeugte Code ist ein guter Anfang, aber prüfe ihn. Legst du eine Variable zuerst an und liest sie später mit einer Eingabe neu ein, schreibt VisuStruct trotzdem `int pin = scanner.nextInt();`. Java meldet dann, dass es `pin` schon gibt. Lösche in dieser Zeile einfach das `int`.

web/lessons/de/begriffe.md

@@ -193,5 +193,9 @@ Eine Variable, die direkt in der Klasse steht und nicht in einer Methode. Mit `s
 ### Scanner
 Ein fertiger Baustein von Java, der Eingaben über die Tastatur liest, z. B. mit `scanner.nextInt()` eine Zahl. Er braucht ganz oben `import java.util.Scanner;`.
 
+### Kommentar
+auch: Kommentare, Kommentaren, Kommentars
+Eine Notiz im Code für Menschen. Java überspringt sie beim Ausführen. `//` gilt bis zum Ende der Zeile, `/* … */` kann über mehrere Zeilen gehen.
+
 ### import
 Eine Zeile ganz oben im Java-Code, die einen fertigen Baustein aus einem Paket holt, z. B. `import java.util.Scanner;`. Ohne sie kennt Java den Namen nicht.

web/lessons/de/nachschlagen.md

@@ -138,3 +138,23 @@ boolean[][] sitze = new boolean[3][5]
 sitze[1][4] = true
 output: sitze.length + " Reihen, " + sitze[0].length + " Plätze"
 ```
+
+## Java
+
+### Kommentare
+
+Notizen im Code. Java überspringt sie, das Struktogramm bleibt gleich.
+
+```java
+/*
+ * Aufgabe: die Zahlen von 1 bis 10 addieren
+ * (mehrzeiliger Kommentar)
+ */
+// Verarbeitung (einzeiliger Kommentar)
+int summe = 0;
+for (int i = 1; i <= 10; i++) {
+    summe = summe + i;      // Kommentar hinter dem Code
+} // Ende for
+```
+
+Gut für: die Aufgabenstellung, die Einteilung in Eingabe, Verarbeitung und Ausgabe, eine Erklärung, das Ende eines Blocks hinter `}`, die erwartete Ausgabe und Notizen fürs nächste Mal.

web/lessons/en/06-eingabe-und-ausgabe.md

@@ -13,6 +13,7 @@ kurz: Ask for values, show results and use the IPO model.
 - work out a result first and store it in a variable, then output that variable, e.g. `int sum = a + b`, then `output: sum`
 - pick out input, process and output from a task
 - read numbers in Java with the scanner
+- write comments with `//` and `/* */` and use them to structure and explain my code
 :::
 
 ## The IPO model
@@ -168,6 +169,75 @@ tipp: `int years = scanner.nextInt();` reads. `int days = years * 365;` calculat
 lösung: l06-java-tage-loesung.visustruct
 :::
 
+## Comments in code
+
+You may write notes in your code. They are called **comments**. Java skips them when it runs, so the program and the structure chart stay the same. There are two kinds:
+
+- `//` turns the rest of the line into a comment. This is a **single-line comment**.
+- `/*` starts a **multi-line comment** and `*/` ends it. Everything in between belongs to the comment, however many lines. Java does not need the stars at the start of the lines in between, they just look tidy.
+
+In finished programs you sometimes also see `/** … */` with two stars at the start. That is a **Javadoc comment**, from which Java can create a description of the program. For you, `//` and `/* */` are enough.
+
+This is the IPO example with comments:
+
+```java editor
+/*
+ * Task: The program asks for two numbers
+ * and outputs their sum.
+ */
+import java.util.Scanner;
+Scanner scanner = new Scanner(System.in);
+
+// Input
+System.out.println("First number?");
+int a = scanner.nextInt();
+System.out.println("Second number?");
+int b = scanner.nextInt();
+
+// Process
+int sum = a + b;      // add the two numbers
+
+// Output
+System.out.println("Sum: " + sum);      // for 3 and 4 I expect: Sum: 7
+
+// Next time: allow decimal numbers too
+```
+
+What comments are good for:
+
+- **The task:** the multi-line comment at the top says what the program should do.
+- **Structure:** `// Input`, `// Process` and `// Output` divide the code by the IPO model.
+- **Explanation:** a comment after a line says what your algorithm does there.
+- **Expectation:** write down which output you expect. When you test, you compare.
+- **Matching brackets:** later you will meet blocks in curly brackets `{ }`. Then, for example, `} // end for` shows which bracket closes what.
+- **Keeping your thoughts:** what do you need to remember when you carry on next time?
+
+Click **Open in editor**, change a comment or add a new one. The structure chart stays the same, and VisuStruct keeps your comments.
+
+> Don't put a comment after every line. Explain what your algorithm does and why, not every single character.
+
+::: angeberwissen
+Both kinds are much older than Java: `/* … */` comes from the language PL/I from 1964, `//` from BCPL from 1967. Java inherited them via C and C++.
+:::
+
+## Fill in the gaps: comments
+
+::: lückentext
+titel: Add the comments
+auftrag: Add the characters so that a multi-line comment with the task is at the top and the other two notes are single-line comments.
+```java
+[[/*]]
+ * Task: The program converts euros to cents.
+ [[*/]]
+int euros = 3;
+[[//]] Process
+int cents = euros * 100;
+[[//]] Output, expected: 300
+System.out.println(cents);
+```
+erklärung: `/*` opens the multi-line comment and `*/` closes it. `//` only lasts until the end of the line, so every note needs its own `//`.
+:::
+
 ## Fill in the gaps: input
 
 ::: lückentext
@@ -283,6 +353,7 @@ Rate yourself honestly for each point: ☂️ not yet, ⛅ partly, ☀️ I can
 - I can work out a result first and store it in a variable, then output that variable, e.g. `int sum = a + b`, then `output: sum`. → Careful with + in an output
 - I can pick out input, process and output from a task. → From the task to the structure chart
 - I can read numbers in Java with the scanner. → Now in Java
+- I can write comments with `//` and `/* */` and use them to structure and explain my code. → Comments in code
 :::
 
 ## Quiz
@@ -328,4 +399,18 @@ Rate yourself honestly for each point: ☂️ not yet, ⛅ partly, ☀️ I can
 - [ ] A decimal number
 - [ ] A whole sentence
 > For decimal numbers there is `scanner.nextDouble()`, for a word `scanner.next()`.
+
+? What does Java do with a comment?
+→ Comments in code
+- [ ] It outputs it as text.
+- [x] It skips it.
+- [ ] It reports an error.
+> Comments are notes for people. The program runs exactly the same with or without them.
+
+? Where does a comment that starts with `/*` end?
+→ Comments in code
+- [x] At `*/`
+- [ ] At the end of the line
+- [ ] At the next empty line
+> That is why a comment with `/*` can span several lines. A comment with `//`, on the other hand, ends at the end of the line.
 :::

web/lessons/en/14-verschachteln.md

@@ -97,13 +97,15 @@ int count = 0;
 for (int i = 1; i <= n; i++) {
     if (i % 2 == 0) {
         count++;
-    }
-}
+    } // end if
+} // end for
 System.out.println(count);
 ```
 
 What is nested in the structure chart is nested in curly brackets in Java. Every level is indented four spaces further. If your code gets messy, the **Indent** button at the top of the Programming area helps.
 
+With many closing brackets `}` it is easy to lose track: which bracket belongs to which block? A comment after it tells you, for example `} // end if` and `} // end for`. This also helps when you carry on later.
+
 `count++` is short for `count = count + 1`.
 
 ::: übung l14-java-treppe

web/lessons/en/20-java.md

@@ -98,10 +98,12 @@ public class TimesTable {
         System.out.println("Which times table?");
         int number = scanner.nextInt();
         ...
-    }
-}
+    } // end main
+} // end class
 ```
 
+The comments `// end main` and `// end class` after the last two brackets are not needed, but very helpful: you see at once which bracket closes what, and you don't forget one.
+
 The name of the class comes from the **title** of the diagram. The file must have exactly the same name, so here `TimesTable.java`. **Save Java…** takes care of that for you.
 
 > The generated code is a good start, but check it. If you first create a variable and later read it in again with an input, VisuStruct still writes `int pin = scanner.nextInt();`. Java then reports that `pin` already exists. Simply delete the `int` in that line.

web/lessons/en/begriffe.md

@@ -198,5 +198,9 @@ An error that only happens while the program runs, for example an index outside
 ### Scanner
 A ready-made Java building block that reads input from the keyboard, for example a number with `scanner.nextInt()`. It needs `import java.util.Scanner;` at the very top.
 
+### comment
+auch: comments, Comment, Comments
+A note in the code for people. Java skips it when it runs. `//` lasts until the end of the line, `/* … */` can span several lines.
+
 ### import
 A line at the very top of Java code that fetches a ready-made building block from a package, for example `import java.util.Scanner;`. Without it, Java doesn't know the name.

web/lessons/en/nachschlagen.md

@@ -138,3 +138,23 @@ boolean[][] seats = new boolean[3][5]
 seats[1][4] = true
 output: seats.length + " rows, " + seats[0].length + " seats"
 ```
+
+## Java
+
+### Comments
+
+Notes in the code. Java skips them, the structure chart stays the same.
+
+```java
+/*
+ * Task: add the numbers from 1 to 10
+ * (multi-line comment)
+ */
+// Process (single-line comment)
+int sum = 0;
+for (int i = 1; i <= 10; i++) {
+    sum = sum + i;      // comment after the code
+} // end for
+```
+
+Good for: the task, dividing the code into input, process and output, an explanation, the end of a block after `}`, the expected output and notes for next time.