You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As we know from the chapter <info:structure>, comments can be single-line: starting with`//` and multiline: `/* ... */`.
3
+
Wie wir schon aus den vorherigen Kapiteln <info:structure> wissen, können Kommentare einzeilig, beginnend mit `//`, oder mehrzeilig, beginnend mit `/* ... */`, sein.
4
4
5
-
We normally use them to describe how and why the code works.
5
+
Wir schreiben normalerweise Kommentare, um zu beschreiben, wie der Code funktioniert.
6
6
7
-
At first sight, commenting might be obvious, but novices in programming often use them wrongly.
7
+
Auf den ersten Blick mag das Kommentieren offensichtlich sein, aber von Neulingen im Programmieren werden sie häufig falsch verwendet.
8
8
9
-
## Bad comments
9
+
## Schlechte Kommentierung
10
10
11
-
Novices tend to use comments to explain "what is going on in the code". Like this:
11
+
Anfänger tendieren dazu, Kommentare zu verwenden, um zu beschreiben, was der Code "macht". Wie hier:
12
12
13
13
```js
14
-
//This code will do this thing (...) and that thing (...)
15
-
// ...and who knows what else...
14
+
//Dieser Code macht dies (...) und dann jenes (...)
15
+
// ...und wer weiß, was sonst noch...
16
16
very;
17
17
complex;
18
18
code;
19
19
```
20
20
21
-
But in good code, the amount of such "explanatory" comments should be minimal. Seriously, the code should be easy to understand without them.
21
+
Aber in einem guten Code sollte die Menge solcher "erklärenden" Kommentare minimal sein. Im Ernst, der Code sollte auch ohne sie leicht verständlich sein.
22
22
23
-
There's a great rule about that: "if the code is so unclear that it requires a comment, then maybe it should be rewritten instead".
23
+
Dafür gibt es eine großartige Regel: "Wenn der Code so unklar ist, dass er einen Kommentar erfordert, dann sollte er stattdessen vielleicht neu geschrieben werden"
24
24
25
-
### Recipe: factor out functions
25
+
### Prinzip: Funktionen auslagern
26
26
27
-
Sometimes it's beneficial to replace a code piece with a function, like here:
27
+
Manchmal ist es sinnvoll, ein Code-Stück durch eine Funktion zu ersetzen, wie hier:
28
28
29
29
```js
30
30
functionshowPrimes(n) {
31
31
nextPrime:
32
32
for (let i =2; i < n; i++) {
33
33
34
34
*!*
35
-
//check if i is a prime number
35
+
//prüfen, ob i eine Primzahl ist
36
36
for (let j =2; j < i; j++) {
37
37
if (i % j ==0) continue nextPrime;
38
38
}
@@ -43,7 +43,7 @@ function showPrimes(n) {
43
43
}
44
44
```
45
45
46
-
The better variant, with a factored out function`isPrime`:
46
+
Die bessere Variante, mit einer ausgelagerten Funktion`isPrime`:
47
47
48
48
49
49
```js
@@ -65,21 +65,21 @@ function isPrime(n) {
65
65
}
66
66
```
67
67
68
-
Now we can understand the code easily. The function itself becomes the comment. Such code is called *self-descriptive*.
68
+
Jetzt können wir den Code leichter verstehen. Die Funktion selbst wird dabei zum Kommentar. Ein solcher Code wird *selbsterklärend* genannt
69
69
70
-
### Recipe: create functions
70
+
### Prinzip: Funktionen erstellen
71
71
72
-
And if we have a long "code sheet" like this:
72
+
Und wenn wir ein langes "Code-Sheet" wie dieses haben:
73
73
74
74
```js
75
-
//here we add whiskey
75
+
//hier fügen wir Whiskey hinzu
76
76
for(let i =0; i <10; i++) {
77
77
let drop =getWhiskey();
78
78
smell(drop);
79
79
add(drop, glass);
80
80
}
81
81
82
-
//here we add juice
82
+
//hier fügen wir Saft hinzu
83
83
for(let t =0; t <3; t++) {
84
84
let tomato =getTomato();
85
85
examine(tomato);
@@ -90,7 +90,7 @@ for(let t = 0; t < 3; t++) {
90
90
// ...
91
91
```
92
92
93
-
Then it might be a better variant to refactor it into functions like:
93
+
Dann könnte es eine bessere Variante sein, dieses in Funktionen umzuschreiben, wie hier:
94
94
95
95
```js
96
96
addWhiskey(glass);
@@ -111,70 +111,66 @@ function addJuice(container) {
111
111
}
112
112
```
113
113
114
-
Once again, functions themselves tell what's going on. There's nothing to comment. And also the code structure is better when split. It's clear what every function does, what it takes and what it returns.
114
+
Noch einmal, die Funktionen alleine sagen schon aus, was hier passiert. Es gibt nichts zu kommentieren. Und auch die Code-Struktur ist besser, wenn sie aufgeteilt ist. Es ist klar, was jede Funktion tut, was sie nimmt und was sie zurückgibt.
115
115
116
-
In reality, we can't totally avoid "explanatory" comments. There are complex algorithms. And there are smart "tweaks" for purposes of optimization. But generally we should try to keep the code simple and self-descriptive.
116
+
In Wirklichkeit können wir "erklärende" Kommentare nicht völlig vermeiden. Es gibt komplexe Algorithmen. Und es gibt intelligente "Tweaks" (= Anpassungen) zum Zwecke der Optimierung. Aber im Allgemeinen sollten wir versuchen, den Code einfach und selbsterklärend zu halten.
117
117
118
-
## Good comments
118
+
## Gute Kommentierung
119
119
120
-
So, explanatory comments are usually bad. Which comments are good?
120
+
Erklärende Kommentare sind also in der Regel schlecht. Was sind nun gute Kommentare?
121
121
122
-
Describe the architecture
123
-
: Provide a high-level overview of components, how they interact, what's the control flow in various situations... In short -- the bird's eye view of the code. There's a special language [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) to build high-level architecture diagrams explaining the code. Definitely worth studying.
122
+
Beschreibe die Struktur des Codes: Gib einen allgemeinen Überblick über Komponenten, wie diese interagieren, wie der Kontrollfluss in verschiedenen Situation abläuft.. Kurz gesagt -- die Vogelperspektive auf den Code. Es gibt eine spezielle Sprache, [UML](https://de.wikipedia.org/wiki/Unified_Modeling_Language), zum erstellen von allgemeinen Strukturdiagrammen in denen der Code erläutert wird. Definitiv ein Studium wert.
124
123
125
-
Document function parameters and usage
126
-
: There's a special syntax [JSDoc](http://en.wikipedia.org/wiki/JSDoc) to document a function: usage, parameters, returned value.
124
+
Dokumentiere die Funktionsparameter und die Verwendung: Es gibt eine spezielle Syntax, [JSDoc](http://en.wikipedia.org/wiki/JSDoc), um die Verwendung einer Funktion, die Parameter und den Rückgabewert zu dokumentieren.
127
125
128
-
For instance:
126
+
Zum Beispiel:
129
127
```js
130
128
/**
131
-
* Returns x raised to the n-th power.
129
+
* Gibt x zur n-ten Potenz erhöht zurück.
132
130
*
133
-
* @param{number}xThe number to raise.
134
-
* @param{number}nThe power, must be a natural number.
135
-
* @return{number} x raised to the n-th power.
131
+
* @param{number}xDie zu erhöhende Zahl.
132
+
* @param{number}nDie Potenz, muss eine natürliche Zahl sein.
133
+
* @return{number} x auf die n-te Potenz erhöht.
136
134
*/
137
135
functionpow(x, n) {
138
136
...
139
137
}
140
138
```
141
139
142
-
Such comments allow us to understand the purpose of the function and use it the right way without looking in its code.
140
+
Solche Kommentare erlauben es uns, den Zweck der Funktion zu verstehen und sie richtig zu verwenden, ohne in ihren Code zu sehen.
143
141
144
-
By the way, many editors like[WebStorm](https://www.jetbrains.com/webstorm/)can understand them as well and use them to provide autocomplete and some automatic code-checking.
142
+
Übrigens, viele Entwicklungsumgebungen wie[WebStorm](https://www.jetbrains.com/de-de/webstorm/)können diese auch verstehen und verwenden diese, um Autovervollständigungen und einige automatische Code-Überprüfungen anzubieten.
145
143
146
-
Also, there are tools like[JSDoc 3](https://github.com/jsdoc3/jsdoc)that can generate HTML-documentation from the comments. You can read more information about JSDoc at<http://usejsdoc.org/>.
144
+
Außerdem gibt es Tools wie[JSDoc 3](https://github.com/jsdoc3/jsdoc)die aus den Kommentaren eine HTML-Dokumentation generieren können. Weitere Informationen über JSDoc findest du unter<http://usejsdoc.org/>.
147
145
148
-
Why is the task solved this way?
149
-
: What's written is important. But what's *not* written may be even more important to understand what's going on. Why is the task solved exactly this way? The code gives no answer.
146
+
Warum wird die Aufgabe auf diese Weise gelöst? : Was geschrieben wird, ist wichtig. Aber was *nicht* geschrieben ist, kann noch wichtiger sein, um zu verstehen, was vor sich geht. Warum wird die Aufgabe genau auf diese Weise gelöst? Der Code gibt keine Antwort.
150
147
151
-
If there are many ways to solve the task, why this one? Especially when it's not the most obvious one.
148
+
Wenn es viele Wege zur Lösung der Aufgabe gibt, warum dann dieser? Vor allem dann, wenn es nicht der offensichtlichste ist.
149
+
150
+
Ohne solche Kommentare ist die folgende Situation möglich:
151
+
1. Du (oder dein Kollege) öffnen den Code, der vor einiger Zeit geschrieben wurde und siehst, das dieser "suboptimal" ist.
152
+
2. Du denkst: "Wie dumm ich damals war, und wie viel klüger ich jetzt bin", und schreibst ihn mit der "offensichtlicheren und korrekteren" Variante um.
153
+
3. ... Der Drang, umzuschreiben, war gut. Aber dabei sieht man, dass die "offensichtlichere" Lösung tatsächlich fehlt. Du erinnerst dich sogar schwach daran, warum, weil du es schon vor langer Zeit versucht hast. Du kehrst zur richtigen Variante zurück, doch die Zeit war verschwendet.
154
+
155
+
Kommentare, die die Lösung erklären sind sehr wichtig. Sei helfen, die Entwicklung auf dem richtigen Weg fortzusetzen.
152
156
153
-
Without such comments the following situation is possible:
154
-
1. You (or your colleague) open the code written some time ago, and see that it's "suboptimal".
155
-
2. You think: "How stupid I was then, and how much smarter I'm now", and rewrite using the "more obvious and correct" variant.
156
-
3. ...The urge to rewrite was good. But in the process you see that the "more obvious" solution is actually lacking. You even dimly remember why, because you already tried it long ago. You revert to the correct variant, but the time was wasted.
157
+
Gibt es subtile Merkmale des Codes? Wo werden sie verwendet? : Wenn der Code irgendetwas Subtiles und diskursives aufweist, ist es auf jeden Fall einen Kommentar wert.
157
158
158
-
Comments that explain the solution are very important. They help to continue development the right way.
159
+
## Zusammenfassung
159
160
160
-
Any subtle features of the code? Where they are used?
161
-
: If the code has anything subtle and counter-intuitive, it's definitely worth commenting.
161
+
Ein wichtiges Zeichen eines guten Programmierers sind Kommentare: ihr Vorhandensein und sogar ihr Nichtvorhandensein.
162
162
163
-
## Summary
163
+
Gute Kommentare ermöglichen es uns, den Code gut zu pflegen, später darauf zurückzukommen und ihn effektiver zu nutzen.
164
164
165
-
An important sign of a good developer is comments: their presence and even their absence.
165
+
**Verwende Kommentare:**
166
166
167
-
Good comments allow us to maintain the code well, come back to it after a delay and use it more effectively.
167
+
- allgemeiner Überblick, Überblick über die Struktur des Codes
168
+
- Verwendung von Funktionen.
169
+
- Wichtige Lösungsansätze, insbesondere wenn sie nicht sofort offensichtlich sind.
168
170
169
-
**Comment this:**
171
+
**Vermeide Kommentare:**
170
172
171
-
- Overall architecture, high-level view.
172
-
- Function usage.
173
-
- Important solutions, especially when not immediately obvious.
173
+
- Welche beschreiben "wie Code funktioniert" oder "was er tut"
174
+
- Setze sie nur dann ein, wenn es unmöglich ist, den Code so einfach und selbsterklärend zu gestalten, dass er sie nicht benötigt.
174
175
175
-
**Avoid comments:**
176
-
177
-
- That tell "how code works" and "what it does".
178
-
- Put them in only if it's impossible to make the code so simple and self-descriptive that it doesn't require them.
179
-
180
-
Comments are also used for auto-documenting tools like JSDoc3: they read them and generate HTML-docs (or docs in another format).
176
+
Kommentare werden auch für Autodokumentations-Tools wie JSDoc3 verwendet: sie lesen diese und erzeugen HTML-Dokumente (oder Dokumente in einem anderen Format)
0 commit comments