Wie kann ich Bemerkungen in den Quelltext eingeben?

[Joergi]

Hi, wie kann ich bemerkungen in den Quelltext eingeben, so das ich das nächste mal gleich bescheid weiss was ich gemacht habe. kann mir jemand helfen?

[Gunnar Bittersmann]

@@Joergi

wie kann ich bemerkungen in den Quelltext eingeben

Kommentare

so das ich das nächste mal gleich bescheid weiss was ich gemacht habe.

“When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous.” —Martin Fowler via @CodeWisdom

LLAP 🖖

[1unitedpower]

“When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous.” —Martin Fowler via @CodeWisdom

Das würde ich noch stärker formulieren:

*“When you feel the need to write a comment, first try to refactor the code so that any comment becomes superf”

Denn selbst sprechender Code ist nicht selbstsprechend. Den Kalauer konnte ich mir nicht verkneifen. Aber im Ernst, auch nachvollziehbarer Code wird duch angemessene Kommentare nur noch besser verständlich und überhaupt erst relevant. Weil selbstsprechender Code ein Mythos ist − Eric Holscher (Mitgründer von https://readthedocs.org/)

Trotzdem sind die Momente, die man mit dem Dokumentieren von Code verbringt, ausgezeichnete Auslöser für Refactoring-Maßnahmen. Denn dann begibt man sich in einen besonderen Zustand der Klarheit mit einem geschärften Blick für das große Ganze und ist sensibilisiert für zu komplex geratene Bereiche der aktuellen Implementierung. Wenn ein Code-Fragment unangemessen erklärungsbedürftig ist, dann sollte man es refactoren, sodass es sich auf möglichst nachvollziehbare und prägnante Art erklären lässt. Und, was auch immer das Fragment tut, es muss dokumentiert werden, denn aus Sicht des Lesers existiert ein undokumentiertes Feature nicht. Diese Schlussfolgerung habe ich im Zitat von Fowler vermisst, sie entstammt dem Documentation Driven Development.

[Auge]

Hallo

Denn selbst sprechender Code ist nicht selbstsprechend. Den Kalauer konnte ich mir nicht verkneifen.

So richtig kalauert er so:

„Selbst selbst sprechender Code ist nicht selbstsprechend.“

*scnr*

Aber im Ernst, auch nachvollziehbarer Code wird duch angemessene Kommentare nur noch besser verständlich …

… wenn nicht (bzw. nicht nur) das Offensichtliche drinsteht.

Tschö, Auge

[Sophie]

<!-- Anfang <div> -->
<div></div>
<!-- Ende </div> -->

Bitte bedenke, jeder der in den Quelltext schaut kann lesen was du dort hinterlassen hast. Also nichts wichtiges und schon gar keine Passwörter dort hinterlassen!

[Gunnar Bittersmann]

@@Sophie

<!-- Anfang <div> -->
<div></div>
<!-- Ende </div> -->

Diese beispielhaften Kommentare sind Unsinn. Kommentare sind nicht dazu da zu wiederholen, was bereits der Code aussagt. Kommentare sind dazu da festzuhalten, was der Code nicht aussagt.

LLAP 🖖

[Gunnar Bittersmann]

@@Gunnar Bittersmann

Diese beispielhaften Kommentare sind Unsinn. Kommentare sind nicht dazu da zu wiederholen, was bereits der Code aussagt. Kommentare sind dazu da festzuhalten, was der Code nicht aussagt.

Ich habe jetzt auch den Fehler im Wiki berichtigt.

LLAP 🖖

[Matthias Apsel]

Hallo Gunnar Bittersmann,

Ich habe jetzt auch den Fehler im Wiki berichtigt.

Vielleicht fällt dir ja ein einfaches und sinnhaftes Beispiel ein⁉️ Oder am besten zwei?

Bis demnächst
Matthias

[Gunnar Bittersmann]

@@Matthias Apsel

Vielleicht fällt dir ja ein einfaches und sinnhaftes Beispiel ein⁉️ Oder am besten zwei?

Ich finde es hilfreich im generierten HTML-Quelltext zu sehen, welches Stück serverseitiger Code welches Markup generiert.

Die View eines Anmeldeformulars könnte so aussehen:

<!-- 🔽 registration-form -->
<form action="…">
	⋮
</form>
<!-- 🔼 registration-form -->

Ein Widget zur Passwortvergabe (was Label, Eingabefeld, Element zur Umschaltung der Passwortsichtbarkeit und Hinweise zur Passwortstärke enthält) darin:

<!-- 🔽 password-widget -->
<fieldset class="password-widget">
	⋮
</fieldset>
<!-- 🔼 password-widget -->

Der generierte Quellcode einer Seite sieht dann so aus:

<!-- 🔽 registration-form -->
<form action="…">
	⋮
<!-- 🔽 password-widget -->
<fieldset class="password-widget">
	⋮
</fieldset>
<!-- 🔼 password-widget -->
	⋮
</form>
<!-- 🔼 registration-form -->

LLAP 🖖

[marctrix]

Hej Gunnar,

@@Sophie

<!-- Anfang <div> -->
<div></div>
<!-- Ende </div> -->

Diese beispielhaften Kommentare sind Unsinn. Kommentare sind nicht dazu da zu wiederholen, was bereits der Code aussagt. Kommentare sind dazu da festzuhalten, was der Code nicht aussagt.

Oh, das kann sehr hilfreich sein, besonders wenn ein Programmierer das öffnende Tag in einer anderen Datei notiert hat, als das schließende. Ob das Sinn macht? Nö? Ob das gut ist? Nö.

Aber es kommt vor… :-}

Marc

[pl]

Oh, das kann sehr hilfreich sein, besonders wenn ein Programmierer das öffnende Tag in einer anderen Datei notiert hat, als das schließende. Ob das Sinn macht? Nö? Ob das gut ist? Nö.

Aber es kommt vor… :-}

Schlimmer ist, wenn der Code so falsch ist, dass die Kommentare überhaupt nicht mehr dazu passen.

[marctrix]

Hej pl,

Schlimmer ist, wenn der Code so falsch ist, dass die Kommentare überhaupt nicht mehr dazu passen.

Klar, wenn man sich genug Mühe gibt, kann man alles auch noch schlechter machen.

😉

Marc

[pl]

Einen besonders schönen Kommentar fand ich hier:

$key .= '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'; # WTF

gefunden in package Protocol::WebSocket::Response; (Perl Module)

Tja, für manche ein Globally Unique Identifier für andere halt WTF 😀

MfG 😉

[Regina Schaukrug]

Erklärung.

Man suche dort nach: 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 bzw. Globally Unique Identifier

[Rolf B]

Hallo pl,

falsch - oder verändert. Kommentarfäule ist ein häufiger Defekt in Legacy-Code…

Rolf

[Gunnar Bittersmann]

@@marctrix

<!-- Anfang <div> -->
<div></div>
<!-- Ende </div> -->

Diese beispielhaften Kommentare sind Unsinn. Kommentare sind nicht dazu da zu wiederholen, was bereits der Code aussagt. Kommentare sind dazu da festzuhalten, was der Code nicht aussagt.

Oh, das kann sehr hilfreich sein

Nein.

besonders wenn ein Programmierer das öffnende Tag in einer anderen Datei notiert hat, als das schließende. Ob das Sinn macht? Nö? Ob das gut ist? Nö.

Hierin sind wir uns völlig einig.

Aber es kommt vor… :-}

Dann sollte der Fehler behoben, nicht kommentiert werden.

Und wenn schon, dann sowas wie <!-- Anfang Komponente Foo -->, nicht <!-- Anfang <div> -->

Also – wie ich sagte, nicht das kommentieren, was im Code steht (<div>); sondern das, was nicht im Code steht (Komponente Foo).

LLAP 🖖

[Sophie]

Wenn du eine sehr große Seite hast mit mehreren Hunderten von <div> dann ist das sehr wohl hilfreich. Gehe nicht immer von dir selber aus!

[MudGuard]

Hi,

Wenn du eine sehr große Seite hast mit mehreren Hunderten von <div>

dann ist das das Problem.

dann ist das sehr wohl hilfreich.

inwiefern hilft ein <!-- hier geht ein div los --> vor einem <div>?

Der Kommentar sagt genau das aus, was das <div> alleine schon sagt.

cu,
Andreas a/k/a MudGuard

[Sophie]

Wenn du mehrere <div> verschachtelt hast, dann hilft es sehr wohl am Ende zu sagen, welche DIV hier gerade geschlossen wird.

[Gunnar Bittersmann]

@@Sophie

Wenn du mehrere <div> verschachtelt hast, dann hilft es sehr wohl am Ende zu sagen, welche DIV hier gerade geschlossen wird.

Was du aber mit <!-- Ende </div> --> eben nicht tust.

Und <!-- Anfang <div> --> ist wie mehrfach gesagt unsinnig.

LLAP 🖖

[Sophie]

Das ist deine Meinung! Ich bleibe bei meiner Meinung! Wenn es für dich unsinnig ist, dann mach es einfach so wie du denkst und lass mich in Ruhe mit deiner Besserwisserei

[Gunnar Bittersmann]

@@Sophie

Ich hab meine Meinung begründet. Und du?

Und @MudGuard soll dich mit seiner Besserwisserei wohl auch in Ruhe lassen‽

LLAP 🖖

[Sophie]

Och Herr Bittersmann nur weil mal jemand nicht deiner Meinung ist, verpasst du einem Posting gleich ein - Da sieht man mal wieder wie verbissen du mit deiner Meinung bist.

[Gunnar Bittersmann]

@@Sophie

Och Herr Bittersmann nur weil mal jemand nicht deiner Meinung ist, verpasst du einem Posting gleich ein - Da sieht man mal wieder wie verbissen du mit deiner Meinung bist.

Das Forumsarchiv widerlegt deine Behauptung.

Allerdings verpasse ich dummdreisten Postings ein Minus – egal ob sie gegen mich oder gegen andere gerichtet sind.

LLAP 🖖

[Sophie]

Nein, du verpasst ein - wenn man anderer Meinung ist als du, siehe Forum-Archiv. Du hast gegen alles etwas was dir nicht passt. Du meinst du bist Mister Gott und es wird gemacht was du willst.

Bestes Beispiel vorhin bei PL da meinst du warum keine DL Liste verwendet wird. Dir geht die Tabelle mal wieder gegen den Strich.

Hast von dir noch nie ein fertiges Projekt gezeigt.

[Gunnar Bittersmann]

@@Sophie

Nein, du verpasst ein - wenn man anderer Meinung ist als du, siehe Forum-Archiv. […]

Bestes Beispiel vorhin bei PL da meinst du warum keine DL Liste verwendet wird. Dir geht die Tabelle mal wieder gegen den Strich.

Bestes Beispiel, richtig. Da habe ich kein Minus verpasst.

Du faselst wirres Zeugs.

LLAP 🖖

[marctrix]

Hej Sophie,

Das ist deine Meinung!

Nein, er hat schon Recht, dass man direkt neben ein öffnendes Tag mit der Klasse foo nicht dran schreiben muss, dass hier ein div mit der Klasse foo beginnt.

Am Ende, wo nur ein </div> steht, dem man nicht ansieht, zu welchem öffnenden Tag es gehört, kann das natürlich sehr wohl hilfreich sein!

Wie auch immer:

Wenn es für dich unsinnig ist, dann mach es einfach so wie du denkst und lass mich in Ruhe mit deiner Besserwisserei

Ich denke, das was man anderen rät, könnte man auch selber tun. Heißt: Mach es einfach so wie du denkst und lass dich auf so einen Streit nicht ein 😉

Marc

[Sophie]

Guten Morgen,

ich bekomme oftmals solcher HTML vorgesetzt

<main>
	
<div class="container">
	<article>
	<h2>H2</h2>
		<article><h3>H3</h3></article>
		<article><h3>H3</h3></article>
	</article>
	<article>
	<h2>H2</h2>
		<div></div>
		<div></div>
	</article>
	<article>
	<h2>H2</h2>
		<div></div>
		<div></div>
	</article>
	<article>
	<h2>H2</h2>
		<div></div>
		<div></div>
	</article>
	<article>
	<h2>H2</h2>
		<div></div>
		<div></div>
	</article>

</div>

</main>

Und da macht es kein Sinn zu sagen, wann ein article anfängt und wo er endet? Oder für was welcher Artikel steht? Ich finde schon.

[marctrix]

Hej Sophie,

Und da macht es kein Sinn zu sagen, wann ein article anfängt und wo er endet? Oder für was welcher Artikel steht? Ich finde schon.

Dann mach es so. - Ich bräuchte es nicht, denn Artikel können ja nicht ineinander verschachtelt werden. Also endet bei </article> immer der aktuelle Artikel.

Marc

PS: Ich gehe davon aus, dass alle div falsch verwendet sind. Ich bin mir ziemlich sicher, dass die alle mit section ersetzt werden sollten… Wenn die sinnvolle mit Klassen versehen werden, brauchst du vermutlich auch weniger Kommentare

[Gunnar Bittersmann]

@@marctrix

denn Artikel können ja nicht ineinander verschachtelt werden.

Doch, können sie.

LLAP 🖖

[marctrix]

Hej Gunnar,

@@marctrix

denn Artikel können ja nicht ineinander verschachtelt werden.

Doch, können sie.

Echt? - Mal wieder so ein Konstrukt, dass ich mir nicht vorstellen kann.

Ich glaube dir, dass das so in der Spec steht, aber weißt du ein sinnvolles Anwendungsbeispiel?

Marc

[Gunnar Bittersmann]

@@marctrix

Ich glaube dir, dass das so in der Spec steht

Es wäre auch einfach nachzulesen.

aber weißt du ein sinnvolles Anwendungsbeispiel?

Ich will mir jetzt keins aus den Fingern saugen, was dann doch nicht so richtig sinnvoll ist.

Aber wenn man mal an den Punkt kommt, wo es sinnvoll ist, article in article zu schachteln, ist es gut, dass die Spec das nicht verbietet. 😉

LLAP 🖖

[marctrix]

Hej Gunnar,

@@marctrix

Ich glaube dir, dass das so in der Spec steht

Es wäre auch einfach nachzulesen.

Da steht nur, was du gesagt hast — ich weiß schon, wem ich was glauben kann 😉

aber weißt du ein sinnvolles Anwendungsbeispiel?

Ich will mir jetzt keins aus den Fingern saugen, was dann doch nicht so richtig sinnvoll ist.

Aber wenn man mal an den Punkt kommt, wo es sinnvoll ist, article in article zu schachteln, ist es gut, dass die Spec das nicht verbietet. 😉

Wenn man mal an den Punkt kommt, wo es sinnvoll ist, Absätze in Absätzen zu verschachteln, ist es schlecht, dass die Spec das verbietet. 😉

Es gibt einfach Dinge, die in meinen Augen keinen Sinn machen - bei den leeren Listen habe ich mich ja schon trotz Sträubens überzeugen lassen. Insofern habe ich gedacht, vielleicht hast du was passendes parat. Das Beispiel von MDN finde ich nicht gut. Nicht nur, dass es auf mich reichlich konstruiert wirkt, es ist IMHO auch falsch.

Marc

[MudGuard]

Hi,

Ich glaube dir, dass das so in der Spec steht, aber weißt du ein sinnvolles Anwendungsbeispiel?

Wie wär's damit:

das äußere article ist ein Zeitungsartikel. Das innere ist ein vom Schreiber des äußeren articles zitierter anderer kompletter Zeitungsartikel.

cu,
Andreas a/k/a MudGuard

[marctrix]

Hej MudGuard,

Ich glaube dir, dass das so in der Spec steht, aber weißt du ein sinnvolles Anwendungsbeispiel?

das äußere article ist ein Zeitungsartikel. Das innere ist ein vom Schreiber des äußeren articles zitierter anderer kompletter Zeitungsartikel.

Habe ich zwar noch nie gesehen, aber lasse ich mal gerade so gelten… 😂

Marc

[Sophie]

Wer sagt dass ein Artikel nicht innerhalb von einem Artikel stehen darf? Ich behaupte das Gegenteil: https://developer.mozilla.org/de/docs/Web/HTML/Element/article

[marctrix]

Hej Sophie,

Wer sagt dass ein Artikel nicht innerhalb von einem Artikel stehen darf? Ich behaupte das Gegenteil: https://developer.mozilla.org/de/docs/Web/HTML/Element/article

Du hast recht, aber gerade dieses Beispiel würde ich nie so umsetzen. Sektionen (zu denen auch article gehört) sollten (ich weiß, sie müssen nicht) einen Titel haben und "finde ich auch" ist für mich kein in sich sinnvoll abgeschlossener Text, den man aus dem Zusammenhang gerissen weitergeben kann, ohne dass er unverständlich wird. Für mich sind das eher weiterführende Informationen, weshalb ich mich für ein aside entscheiden würde oder — wenn man die Kommentare als einen Teil des eigentlichen Artikels ansehen würde (main-review und user-review), dann fände ich section angebracht. Zumal der Klassenname "user-review" ja eine nicht umsetzbare Wunschvorstellung ist. Korrekterweise hätte hier eine Klasse "user-comments" verwendet werden müssen, aber dann wäre wohl zu deutlich geworden, dass article nicht das geeignete Element ist. Vermutlich fiel denen bei Mozilla auch kein vernünftiges Beispiel ein…

Marc

[Gunnar Bittersmann]

@@marctrix

https://developer.mozilla.org/de/docs/Web/HTML/Element/article

Du hast recht, aber gerade dieses Beispiel würde ich nie so umsetzen.

Siehste, wenn ich gesaugt hätte, wäre wohl ähnliches bei rausgekommen.

Ich finde auch, dass Kommentare i.d.R. keine eigenen article sind und dass das Beispiel in der Spec besseres Markup ist.

Das könnte aber schon anders aussehen bei Diskussionen in Mailinglisten. Oder Foren …

LLAP 🖖

[marctrix]

Hej Gunnar,

@@marctrix

https://developer.mozilla.org/de/docs/Web/HTML/Element/article

Du hast recht, aber gerade dieses Beispiel würde ich nie so umsetzen.

Siehste, wenn ich gesaugt hätte, wäre wohl ähnliches bei rausgekommen.

es zeigt halt gut, wie schwer es ist, sich sinnvoll einen oder mehrere Artikel in einem anderen vorzustellen.

Aber wie du schon sagtest: vielleicht braucht man es ja mal! - Dann werde ich das aber so was von dermaßen ausnutzen!

Ich finde auch, dass Kommentare i.d.R. keine eigenen article sind und dass das Beispiel in der Spec besseres Markup ist.

Das könnte aber schon anders aussehen bei Diskussionen in Mailinglisten. Oder Foren …

Ja, es ist auch weit verbreitet, Kommentare in Artikel-Elemente zu packen. Wenn ich das Gefühl habe, dass das zum Quasi-Standard geworden ist, mache ich das sogar mit, weil ich Konventionen liebe — noch mehr als ich es ablehne Kommentare in Artikel zu packen 😉

Marc

[Gunnar Bittersmann]

@@Sophie

Und da macht es kein Sinn zu sagen, wann ein article anfängt und wo er endet? Oder für was welcher Artikel steht? Ich finde schon.

Das hat auch niemand bestritten. Im Gegenteil.

LLAP 🖖

[marctrix]

Hej MudGuard,

Wenn du eine sehr große Seite hast mit mehreren Hunderten von <div>

dann ist das das Problem.

Ja, die Frage ist, ob man darauf Einfluss hat. Wenn man als Frontender so etwas vorgesetzt bekommt, schreibt man die Anwendung nicht mal eben neu. - Wenn man den Quellcode ändern kann, schreibe ich mir schon manchmal Dinge rein, die für mich sinnvoll sind.

Ob die jemand anders benötigt, ist mir vollkommen Wurscht.

dann ist das sehr wohl hilfreich.

inwiefern hilft ein <!-- hier geht ein div los --> vor einem <div>?

Der Kommentar sagt genau das aus, was das <div> alleine schon sagt.

War das nicht nur ein Beispiel? Bei öffnenden Tags finde ich das auch nicht nötig.

So was mache ich schon manchmal in besonders umfangreichen Seiten:

</div><!-- .widget-login -->

oder

</aside><!-- #sidebar -->

Marc

[Gunnar Bittersmann]

@@marctrix

inwiefern hilft ein <!-- hier geht ein div los --> vor einem <div>? Der Kommentar sagt genau das aus, was das <div> alleine schon sagt. War das nicht nur ein Beispiel?

Ja, es war ein Beispiel. Genau darauf bezog sich meine Kritik: „Diese beispielhaften Kommentare sind Unsinn.“

Nein, es war nicht nur ein Beispiel. Beispiele müssen sinnvoll sein, damit man sich an ihnen ein Beispiel nehmen kann.

LLAP 🖖

[Gunnar Bittersmann]

@@Sophie

Wenn du eine sehr große Seite hast mit mehreren Hunderten von <div>

dann ist das Markup kaputt.

Es gibt andere HTML-Elemente als div (auch wenn böse Zungen anderes behaupten).

dann ist das sehr wohl hilfreich.

Nein.

Hilfreich wäre evtl. sowas wie

<div id="foo">
	⋮
</div> <!-- id="foo"-->

was im Prinzip dem von mir bereits genannten

<!-- Anfang Komponente Foo -->
<div id="foo">
	⋮
</div>
<!-- Ende Komponente Foo -->

entspricht.

Gehe nicht immer von dir selber aus!

Keine Sorge, tu ich nicht.

LLAP 🖖

[Matthias Apsel]

Hallo Gunnar Bittersmann,

Hilfreich wäre evtl. sowas wie

<div id="foo">
	⋮
</div> <!-- id="foo"-->

Genau. Deshalb finde ich das auch beinahe als das sinnvollere Beispiel fürs Wiki gegenüber

<!-- Anfang Komponente Foo -->
<div id="foo">
	⋮
</div>
<!-- Ende Komponente Foo -->

Bis demnächst
Matthias

[Auge]

Hallo

Hilfreich wäre evtl. sowas wie

<div id="foo">
	⋮
</div> <!-- id="foo"-->

Genau. Deshalb finde ich das auch beinahe als das sinnvollere Beispiel fürs Wiki gegenüber

<!-- Anfang Komponente Foo -->
<div id="foo">
	⋮
</div>
<!-- Ende Komponente Foo -->

Ich finde: Jein.

Ja, mit <!-- id="foo"--> hat man im Editor koopierbaren Text für die Suche. Das ist hilfreich. Nein, mit <!-- id="foo"--> allein erschließt sich mir der Zweck des Codes nach einiger Zeit bestimmt nicht so gut, wie mit <!-- Ende Komponente Foo -->. Voraussetzung ist natürlich, da steht, so, wie es Gunnar in einem anderen Posting zeigt, statt „Foo“ der tatsächliche Zweck des Blockes drin.

Wahrscheinlich ist, je nach Anwendungsfall, eine Kombination vorzuziehen (z.B. <!-- Ende Komponente Foo (id="foo") -->). Da ist die Beschreibung und kopierbarer Code vorhanden.

Tschö, Auge

[Sophie]

Nur mal so zu Info Herr Bittersmann: Ein <main> braucht keine id="main"

[Gunnar Bittersmann]

@@Sophie

Nur mal so zu Info Herr Bittersmann: Ein <main> braucht keine id="main"

Wenn es als Sprungmarke dienen soll, dann schon.

Wenn du hier klugscheißen willst, solltest du mehr auf Tasche haben.

LLAP 🖖

[Sophie]

Du legst dir alles so, wie du es brauchst. Soll ich mal heraussuchen wie oft die gesagt hast, dass ein main keine ID braucht? Ach jetzt geht es um deine Seite, da braucht man es natürlich!

[Gunnar Bittersmann]

@@Sophie

Soll ich mal heraussuchen wie oft die gesagt hast, dass ein main keine ID braucht?

Ich bitte darum.

LLAP 🖖

[Sophie]

Da muss ich mich bei dir entschuldigen. Ich habe id mit role verwechselt.
Das zweite braucht man nicht mehr! Entschuldige bitte!

[Joergi]

Danke, hat mir sehr geholfen