Dokumenation von Quelltext

[vimix]

Ich mache mir gerade Gedanken darüber wie ich meinen in der Zukunft entstehenden Quelltext dokumentieren soll.
Bisher habe ich die Dokumentation direkt in den Quelltext mittels Javadoc-/Doxygentags geschrieben. Mittlerweile
bin ich jedoch der Meinung, dass das den Quelltext sehr aufbläht. Moderne IDEs kompensieren das zwar sehr gut,
aber naja...
Interessensshalber habe ich gerade in den FreeBSD-Codetree geschaut und gesehen, dass auch so große Projekte
ohne auskommen. (auch wenn derart alter Code heutzutage mit einem anderen Maß gemessen werden muss.)

Jetzt zu den Fragen die ich hier gerne diskutieren will.

Hat eine derartige Dokumentation des Quelltextes innerhalb des selben wirklich Vorteile?
Gibt es alternative Methoden um eine derartige Dokumentation extern zu erzeugen?

[zwergmulch]

Hi, da ist wohl mal wieder einer der tatsächlich seinen Code kommentiert? :shock: :D
Oder vielleicht doch nicht?

Mittlerweile bin ich jedoch der Meinung, dass das den Quelltext sehr aufbläht.

Hast recht, wozu auch Kommentare. Und noch möglichst viel Goto. Sch*** auf die Wartbarkeit. :roll: :lol:

Hat eine derartige Dokumentation des Quelltextes innerhalb des selben wirklich Vorteile?

Nunja, du hast Kommentare und Dokumentation auf einen Schlag, sprich

• Andere Leute können sich leichter in deinen Quelltext einarbeiten/fertige Funktionen davon nutzen.
• Du arbeitest dich nach einer (längeren) Pause leichter wieder ein.

Gibt es alternative Methoden um eine derartige Dokumentation extern zu erzeugen?

Klar, du kannst per Hand via Notepad, Word oder in HTML die Dokumentation schreiben. ;)
Viel Spaß dabei! :twisted:

Grüße zwergmulch, der heute wohl seinen ironischen Tag hat. Bitte nicht übel nehmen.

[Jonathan]

Ich finde doxygen eigentlich fast ideal. Es hat schon einige Vorteile, die Dokumentation direkt neben dem Code zu haben, wenn man nicht zwischen programmieren und dokumentieren umschalten muss, macht man da viel eher mal etwas mit. Und auch wenn man fremden Code liest, hilft es einfach, die Dokumentation daneben stehen zu haben. Und man kann natürlich aus den Kommentaren noch schicke Dokumentation in HTML oder so erzeugen.
Solange mir niemand etwas noch besseres zeigt, bin ich von Doxygen auf jeden Fall überzeugt.

[Thoran]

Ich finde Doygen auch super. Aber mann musss natürlich auch sinnvolle Dokumentation dazuschreiben, sonst hilft Doxygen nix.

Bisher habe ich die Dokumentation direkt in den Quelltext mittels Javadoc-/Doxygentags geschrieben. Mittlerweile
bin ich jedoch der Meinung, dass das den Quelltext sehr aufbläht.

Ich halte mich an die Konvention die Funktionen mittels Doxygen nur im Header zu dokumentieren. Damit bleiben die *.cpp Dateien klein mit Ausnahme von direkten Kommentaren zum Verständnis eines Algorithmusteils.

Für Bibliotheken finde ich eine gute Dokumentation unabdingbar. Ob man auf diese Weise das eigenen Programme(im Sinne von *.exe) dokumentieren muss, ist Geschmacksache, aber bestimmt nicht verkehrt.

Thoran

[vimix]

Hast recht, wozu auch Kommentare. Und noch möglichst viel Goto. Sch*** auf die Wartbarkeit. :roll: :lol:

Bitte nicht die Kommentare mit Javadoctags verwechseln. Ich sage nicht, scheiß auf Kommentare.
Wartbarkeit und Doxygen sollten imho so wenig wie möglich miteinander zu tun haben.
Auf den Sinn und Unsinn von Goto gehe ich hier garnicht ein. :)

Nunja, du hast Kommentare und Dokumentation auf einen Schlag, sprich

* Andere Leute können sich leichter in deinen Quelltext einarbeiten/fertige Funktionen davon nutzen.
* Du arbeitest dich nach einer (längeren) Pause leichter wieder ein.

Naja, hier liegt oft ein Hund begraben. Wenn man Doxytags benötigt um sich und anderen das Einarbeiten in den Code zu
ermöglichen/erleichtern, dann kann man vieles am eigenen Code verbessern. In den meisten Fällen sind Doxygenkommentare
doch nur Aussagen, welcher der Code selbst über sich treffen sollte.

Klar, du kannst per Hand via Notepad, Word oder in HTML die Dokumentation schreiben. ;)

Kennt niemand gute Alternativen? Andere Wege und Tools?

[qote]
Grüße zwergmulch, der heute wohl seinen ironischen Tag hat. Bitte nicht übel nehmen.[/quote]
Natürlich nehme ich dir nichts übel. Die Ironie ist genau das, auf was ich auch hinaus wollte.

Ich finde doxygen eigentlich fast ideal. Es hat schon einige Vorteile, die Dokumentation direkt neben dem Code zu haben, wenn man nicht zwischen programmieren und dokumentieren umschalten muss, macht man da viel eher mal etwas mit. Und auch wenn man fremden Code liest, hilft es einfach, die Dokumentation daneben stehen zu haben. Und man kann natürlich aus den Kommentaren noch schicke Dokumentation in HTML oder so erzeugen.

Die Frage ist. Wenn man guten Code schreibt, wann muss man in die Doxygendokumentation schaun? Eigentlich nie.
Ich gebe dir recht, wenn ich schlechten Code vor mir habe, bin ich für jede weitere Dokumentation dankbar.

Für Bibliotheken finde ich eine gute Dokumentation unabdingbar. Ob man auf diese Weise das eigenen Programme(im Sinne von *.exe) dokumentieren muss, ist Geschmacksache, aber bestimmt nicht verkehrt.

Ja, ich suche eine möglichst bequeme Möglichkeit, diese Zusatzdoku aus dem Code rauszubekommen.

[zwergmulch]

Bitte nicht die Kommentare mit Javadoctags verwechseln. Ich sage nicht, scheiß auf Kommentare.
Wartbarkeit und Doxygen sollten imho so wenig wie möglich miteinander zu tun haben.
Auf den Sinn und Unsinn von Goto gehe ich hier garnicht ein. :)

Javadoctags sind imho eine spezielle Art/Syntax von Kommentar, oder etwa nicht.
Und wieso sollten Wartbarkeit und Doxygen nicht viel miteinander zutun haben?
Wie gut auch immer der Code ist, Kommentare (und auch Doc-Kommentare, die ja zusammenfassen sollten was eine Methode/Klasse/etc. leistet)
helfen beim Verständnis. Sicher, wenn man seine Methoden f, g, h usw. nennt braucht man Doxygen,
aber selbst wenn man ihnen verständliche Namen gibt helfen die immmernoch.
Außerdem muss man nicht gleich die (eigentliche) Dokumentation bemühen sondern kann schnell in den Header schauen.

Achja, das "Scheiß auf Kommentare" war Ironie, da es ja imo keinen Grund gibt mit (Doc-)Kommentaren zu geizen (solange sie sinnvoll bleiben).

Naja, hier liegt oft ein Hund begraben. Wenn man Doxytags benötigt um sich und anderen das Einarbeiten in den Code zu
ermöglichen/erleichtern, dann kann man vieles am eigenen Code verbessern. In den meisten Fällen sind Doxygenkommentare
doch nur Aussagen, welcher der Code selbst über sich treffen sollte.

Siehe oben. Außerdem hat man halt gleich automatisch eine HTML-(oder TeX etc.)Dokumentation, wenn man grad nicht in den Code schauen kann.

Ja, ich suche eine möglichst bequeme Möglichkeit, diese Zusatzdoku aus dem Code rauszubekommen.

So etwas ist doch javadoc für Java, wenn ich das richtig verstanden habe.

[Lord Delvin]

Dokumentation sollte eigentlich nur da sein, wo man den eigentlichen Code nicht ansehen kann oder will, also im großen und ganzen in headern von bibliotheken. Ich find doxygen und jml nützlich. Schade dass es sowas wie jml + tools nicht für C++ gibt:-/

// Dokumentation im Code finde ich eigentlich meistens unangebracht, es sei denn um Dinge zu erklären, wenn man tutorialartigen Code schreibt oder wenn man was macht, was nicht intuitiv ist; muss man ja leider manchmal

[grid]

Ich unterscheide jetzt mal zwischen Kommentar und Dokumentation:
- Kommentar ist das, was der/die Entwickler brauchen, um den Sourcecode zu verstehen. Kommentare sind also eine Art kurze private Dokumentation.
- Domkumentation ist das, was Anwender des Codes (z.B. einer API) benutzen oder auch das was ich beim Codereview beilege, damit jemand anderes den Einstieg findet/einen Überblick bekommt.

Soviel zu meiner Definition. Normalerweise finde ich, dass man soetwas nicht zu unterscheiden braucht. Wenn man aber unbedingt die Code-Dateien ohne "überflüssigen" Doku-Balast haben will kann man ja die Dokumentation einer Klasse/Methode in einer Textdatei machen und mit z.B. mit Doxygen(\include <file_path>) an die entsprechenden Stellen verlinken. Somit hätte man eine Unterteilung in die kurzen Kommentare und die Ausführliche Dokumentation.

ALLERDINGS: Ich finde das äußerst unpraktisch und nicht besonders gut zu warten. Denn auch die Dokumentation muss gewartet werden. Es ist schon ziemlich ärgerlich, wenn nach einer Änderung am Code vergessen wurde die Doku zu anzupassen. Ansonsten gilt für mich auch Doku in die Header und Kommentare nur an den Stellen im Code, die nicht intuitiv sind. Spezialfall sind //TODO oder //BUGTICKET Kommentare, über deren Sinn/Unsinn knn man sich streiten. Die sind aber gerade in Teams ziemlich nützlich.

[dronus]

Sobald Funktions/Methoden-Kommentare länger als der Methodencode werden bin ich skeptisch. In der Regel versuche ich dann die Funktionen zu ändern. Der Kommentar kann sowieso nur einen Eindruck vom Wunschverhalten einer Funktion geben und nie exakt die Wirkung beschreiben. Eine Funktion sollte sich so verhalten dass man sie kurz beschreiben kann, wenn man Glück hat verschwindet der Kommentar dann im Funktionsnamen. Z.b. würde ich von getSomething(..) keine Seiteneffekte erwarten. Wird something aufwendig berechnet, nenne ich die Funktion immer computeSomething(..) um auf den Seiteneffekt von Laufzeit/Speicher hinzuweisen. Wenn eine Funktion bei einer Berechnung weitere Resultate als Seiteneffekte erzeugt, sind Kommentare sinnig. So etwas akzeptiere ich allerdings nur dort, wo die zusammenhängenden Resultate aus Performancegründen nötig sind. Ich würde sonst immer versuchen die Funktion in mehrere klar beschreibbare Funktionen zu spalten.

Mittlerweile bin ich ein großer OpenSource-Fan. Ich mache viel mit Java, wo üblicherweise keine Header verwendet werden. Soweit es geht binde ich Fremdcode als Source ein, da ich mich dann nicht auf die Dokumentation verlassen muss sondern den Code selber einsehen kann. Ich würde mich sehr freuen wenn der Code so lesbar wie die Dokumentation wäre. Oft ist die Dokumentation so schlecht dass auch gammeliger Code besser ist :-)

Bei der Programmierung mit C war die Entdeckung von Linux gewaltig. Auf einmal konnte ich ohne große Mühe einen Riesensack Bibliotheken benutzen und jederzeit in den Code sehen wenn mir irgenwas spanisch vorkam. Das ergab einen dramatischen Produktivitätsschub und ich sehe das als Hinweis darauf das Dokumentation dramatisch überbewertet ist!

[kimmi]

Man kann übrigens auch per Doxygen komplette Tutorials und API-Dokumantationen mit allem Pipapo schreiben. Und ich halte Dokumentationen der öffentlichen Schnittstellen mit den Klassen-Contracts für eine sehr wertvolle Dokumentation einer Lib / Applikation. Gerade das Verhalten im Fehlerfall ist für Benutzer interessant und da schreibe ich lieber einen Satz mehr als zu wenig. Schließlich sind offene Flanken potentielle Support-Anfragen, die Benutzer abschrecken oder mir irgendwann Arbeit machen -> schlecht. Und da ich im Job an einem Framework arbeite, konnte ich mir dort schon Arbeit von der Backe halten -> gut.
Bei privaten internen Schnittstellen gehe ich nicht so weit, die Doku massivst aufzublähen und alles mit Beispielen zu untermauern. Ein kurzer Hinweis, was eine Metode macht, reicht mir. Wenn der Methoden- oder Funktions-Name nicht grob erklärt, was das Stück Code macht, versuche ich, das zu optimieren. Kommentare im Code baue ich nur an den Stellen ein, wo es meiner Ansicht nach nicht anders geht ( kurze Erklärung eines komplexes Alogorithmus mit Verweisen zu detailierter Doku zum Beispiel ). Ansonsten versuche ich den Code an sich so weit es geht selbsterklärend zu schreiben.
Ich halte Doxygen für eine gute Sache und das Generieren einer kompletten Doku aus dem Code heraus für besser als Pflegen parallel aufwachsener Dokumente, die meiner Erfahrung nach nie aktuell sind. Allerdings sollte man Doxygen nicht als Referenz-Doku-Generator allein mißbrauchen. So eine generierte Doku hilft niemanden. Wenn man aber mittels Doxygen ein wirklichen Leitpfaden mit Beispielen aufbaut, kann das ein wirklich wichtigen Werkzeug sein.
Und ja, bei Assimp benutze ich ständig die Doxygen-Hilfe.

Gruß Kimmi

[Jonathan]

Natürlich sollte man sinnvolle Funktionsnamen haben, die angesprochene Sache mit dem computeSOmething statt getSomething mach ich z.B. auch und das ist auch um einiges sinnvoller, als nur ein Kommentar mit dem erwarteten Aufwand daneben zu schreiben. Den Namen sieht man schließlich auch überall, wo man die Funktion aufruft, die Dokumentation dagegen viel seltener.
Aber trotzdem sind Doxygen Kommentare toll, ich versuche z.B. zu jeder Klasse einen kurzen Text zu verfassen, wofür genau sie zuständig ist, und wofür eben nicht. Alleine das schreiben dieses Absatzes ist wirklich sinnvoll, weil oft hat man die Ideen zwar grob im Hinterkopf, entdeckt Fehler aber erst, wenn man sie mal ausformuliert. Ich habe schon einige male beim Kommentare schreiben gemerkt, dass ich eigentlich erst noch den Quellcode verbessern muss.
Je mehr Zeit man beim schreiben des Codes verbringt, desto weniger verschwendet man damit, ihn neu zu schreiben.

[kimmi]

Es heißt ja nicht ohne Grund, man dokumentiert private in der Regel für sich selbst. Da findet man durch das Reflektieren des eigenen COdes gern mal einen Schnitzer. Das gepaart mit Integrationstests haben mir schon viele Fehler vor dem Release offenbahrt. Und das allein sorgt schon dafür, daß ich zumindest eine kurze Doku je Methode / Funktion schreibe.

Gruß Kimmi

[NytroX]

Also für mich ist es sehr wichtiig, dass ich in den Kommentaren alles finde was ich zum verstehen des Sources brauche.
Demnach schreibe ich auch ab und zu etwas mehr, wenn nicht klar ist, wie etwas zusammenhängt.
Ausserdem finde ich persönlich immer wichtig zu wissen, WARUM man etwas so programmiert hat, wie es jetzt da steht.

Die Doku der API o.ä. würde ich garnicht in den Source schreiben.
Meiner Meinung nach sind Doxygen und co. meist überflüssig, weil das Ergebnis keine sinnvolle verwendung hat.

Zu einer Doku gehören so viele Teile, dass es im Code einfach keinen Sinn macht, das zu hinterlegen.
Da fängt es an mit einer allgemeinen Übersicht, den verwendeten Konzepten usw. um sich einen groben Überblick zu verschaffen.
Danach geht es dann darum einige Themenbereiche näher zu erläutern, sowie die öffentliche API zu beschreiben.

Als Beispiel nehme ich mal eine DirectX Doku.
Was sehen wir hier alles?

Zunächst kommt mal ein grobes Themenverzeichnis und ein Kapitel namens "Programming Guide".
Darin werden z.B. Konzepte erläutert wie Buffer, Ressourcen, usw.
Weiterhin gibt es generelle Tipps & Tricks zu der Verwendung.
Ich sehe keinen Platz, wo ich das in Doxygen o.ä. sinnvoll platzieren würde.

Der zweite Teil "Reference" besteht dann letztendlich in der Auflistung der Interfaces usw.
Hier könnte man gut mit Doxygen und co. arbeiten.
Aber: nur der offizielle Teil (API) gehört hier rein.
Und wenn ich dann im Source sehe, dass es für die Hälfte der Funktionen Doxygen/Javadoc Tags gibt, und für die andere Hälfte nicht, finde ich das auch nicht wirklich toll.

Tutrials usw. in den Source zu packen ist auch irgendwie Quatsch.


Daher find ich Kommentare im Source und eine externe Doku am besten.
Ein Wiki macht sich da meist ganz gut, da kann man dann auch Links setzen uvm.


Mal ein paar andere Beispiele:

SFML: Sehr schön ist hier das Wiki mit Tutorials.
In die Doxygen Doku schaut man doch eher selten. Schaut euch z.B. mal die Klasse "sf::Clock" im Doxygen dort an. Die einzige wichtige Info da drin ist, dass die "GetElapsedTime"-Methode die Zeit in Sekunden zurückgibt.
Z.B. das "Clock()" der Default Contructor ist, da wäre ich vermutlich noch selbst drauf gekommen, aber den ganzen Text hat ja mal jemand eingetippt.

AssImp:
Wichtig wären hier für mich 4 Sachen:
- Wie lade ich Files?
- Wie sieht die Struktur aus, die AssImp mir letztendlich zur Verfügung stellt?
- Was wird unterstützt (z.B. in welchem Format werden Animationen, usw. mit verarbeitet)?
- Wie füge ich meinen eigenen Loader ein?
Für alles weitere ging vermutlich unnötig viel Zeit drauf (abgesehen von der Website, eine gute Präsentation halte ich für wichtig, dafür Daumen hoch).
PS: Überragende Library übrigends, gibt nichts vergleichbares! Großes Lob an der Stelle, auch im Bezug auf die Wahl der Lizenz ("Frei" bedeutet für mich auch, die Freiheit zu haben, meinen Source NICHT zu veröffentlichen)!


Ganz wichtig finde ich auch noch die Anmerkung, dass die Doku immer mit gepflegt werden muss! Also, je weniger Doku ich habe, umso weniger muss ich pflegen.
Daher gilt für mich: So wenig Doku wie möglich, so viel Doku wie nötig.

Aber das ist alles natürlich nur meine persönliche Meinung, also Danke fürs lesen und lasst euch nicht aufhalten :-)

Gruß, NytroX.

[Chromanoid]

Ich persönlich bin großer fan von dokumentations-systemen wie javadoc oder doxygen. Mit der richtigen IDE wird das ganze während des programmierens im codesense fenster o.ä. kontextabhängig angezeigt. man muss sich einfach mal die java api referenz anschauen. da sieht man wie sinnvoll man javadoc einsetzen kann. insbesondere im team ist so etwas ziemlich sinnvoll, da man nicht immer einfach mal eben den quellcode anschauen kann. dafür liest man sich dann schnell das javadoc zur jew. fremden klasse durch und fertig...

[The_Real_Black]

Erfahrungen mit C# und Assembler (C++, Java, HTML usw...) zeigen mir, dass jede Klasse, jede Methode und im Falle von Assembler jede Zeile kommentiert werden sollte. Was kann der Input sein, was der Returnwert und kann eine Exception geworfen werden. Zusätzlich sollten "Blöcke" kommentiert werden (in C# #region xy) um einen groben Ablauf von Methoden zu zeigen (besonders bei EVA Prinzip). Dazu benötigt eine gute Dokumentation auch eine Klassenübersicht UML, Ablaufdiagramme und Co.

[Chromanoid]

Das grenzt ja an Nekromantie, ich habe den Verursacher-Beitrag (Globale Operatoren/Funktionen mit Doxygen dokumentieren) mal herausgetrennt.
@The_Real_Black: Ich gehe mal davon aus, dass du nicht mitbekommen hast, dass es sich hier um eine neue Frage handelte. Da deine Antwort viel besser zum OP passt, lasse ich deine Antwort mal hier.

[pUnkOuter]

Guter Code braucht eigentlich keine Dokumentation, ausser den Schnittstellen nach aussen, natürlich, und wenn man eine Library für andere Leute schreibt. Aber wenn ein erfahrener Programmierer den Code ohne Kommentare nicht versteht, dann ist es einfach schlechter Code.

[simbad]

Das mag ich so nicht stehen lassen.
Es gibt Situationen in denen man nicht daran vorbeikommt auch mal Formulierungen zu wählen, die sich einem nicht sofort erschliessen. So bin ich aktuell gerade gezwungen eine Funktion in Assembler zu schreiben und diese mit einigen Tricks zu versehen, weil der Prozessor ein paar Dinge kann und auch nicht kann, die vom Compiler nicht abgedeckt werden.
Da kommt man dann ohne Kommentare oder Dokumentation nicht mehr zurecht. Das mit dem Assembler ist zwar ein extrem, macht aber deutlich, das es einfach eine Frage der Anforderungen ist, ob ich meinen Code verständlich schreiben kann oder nicht.

Es ist vielmehr der Fall, das der Programmierer sich, sofern es keine Randbedingung gibt, die das verhindern, eines gut lesbaren Stils befleissigen sollte, um zusätzliche Dokumentation zu vermeiden.

[RustySpoon]

Ich find's ja immer irgendwie amüsant, wie sich die Leute über "alles muss dokumentiert werden" vs. "nichts muss dokumentiert" werden in die Haare kriegen. Meines Erachtens ist das schlicht und einfach eine Frage, was die jeweilige Sprache an Abstrahierung und High-Level-Features zu bieten hat.

Meine absolute Traumsprache hätte z.B. mal ein richtig geiles und starkes Typsystem, nicht nur so das Larifari was C++ und Konsorten anbieten. Mehr noch: Sauberes Design by Contract.

Was kann der Input sein, was der Returnwert und kann eine Exception geworfen werden.

Das wir meinen, sowas dokumentieren zu müssen, liegt z.B. schlicht und einfach daran, dass wir den Wertebereich von Variablen nicht IN der Sprache genau spezifieren können. Wir können halt irgendwie sagen: "ist sowas ähnliches wie eine ganze Zahl" (int), "ist sowas ähnliches wie eine natürliche Zahl" (unsigned int) oder "ist eine Zeichenkette". Aber viel schöner wäre, wenn ich sowas wie echte Randbedingungen auf Variablen hätte ("a liegt in { 1-10, 42, 100 }"), die dann auch entsprechend vererbt werden könnten ("b = a + 1, ergo: b liegt in { 2-11, 43, 101 }"). Imho merkt man das dann auch gehäuft in schwachtypisierten Sprachen, wo man nicht mal so "grobe" Constraints wie "int", "float" etc. hat, dass sogar das dann extra dokumentiert werden muss.

Das Spiel kann man dann unabhängig vom Typsystem noch weiter denken. Ich merk z.B. dass ich dauernd Dinge dokumentieren muss, die sich eigentlich als Vor-, Nachbedingung oder Invariante ausdrücken ließen, eben Design by Contract. Ich bau beispielsweise im Rahmen eines Uniprojektes einen SAT-Solver und diese Algorithmen sind relativ kompliziert und brauchen aus Effizienzgründen viel ekligen, internen Zustand. Ich dokumentier dann eben so Sachen wie: "forall variable: promising(variable) => score(variable) > 0 and not blocked(variable)". DAS möchte ich eigentlich als Invariante ausformulieren. Das Problem: Sowas geht in C++ halt höchstens über widerliche assert-Konstrukte, aber das bläht den Code auch extrem auf und im Zweifel kriegt man das auch nicht sauber abgeschaltet, weil man hier und da z.B. Hilfsvariablen benötigt - wenn ich z.B. überprüfen möchte, dass container.size() nach einmal aufrufen von push_back(...) wirklich 1 größer ist als vorher. Das ist auch sau schade, weil man viel von diesem Kram schon beim Kompilieren nutzen und Warnungen generieren und der Compiler hier und da sicher tolle, neue Optimierungen auspacken könnte.

Aber um mal wieder die Kurve zum Thema zu kriegen: Ich vermute, dass die Dokumentationsnotwendigkeit direkt aus diesem Dilemma heraus ergibt. Damit ist es halt irgendwo logo das man Assemblercode anders dokumentieren muss als irgendwelchen Code eines high-level Paradigmas. Sauber designte und gelayerte Systeme bedürfen prinzipiell auch weniger Dokumentation auf Codezeilen-Ebene. Dieser Konflikt tritt imho in C++ ziemlich häufig auf, weil die Sprache einfach sehr viele Freiheiten lässt, was Paradigmen und Design-Entscheidungen angeht.

[CodingCat]

Meine absolute Traumsprache hätte z.B. mal ein richtig geiles und starkes Typsystem, nicht nur so das Larifari was C++ und Konsorten anbieten.

Das C++-Typsystem bietet aus Effizienzgründen zwar bewusst Schlupflöcher; wenn du diese aktiv nutzt, bist du jedoch selbst schuld (versehentlich geht nur mit unsicheren C-Style Casts, diese einfach nicht nutzen).

Davon abgesehen verstehe ich nicht, wo das C++-Typsystem für dich larifari ist. Tatsächlich ist C++11 wohl die erste gängige Sprache, in der du einen großen Teil dessen, was du hier beschreibst, sinnvoll selbst implementieren kannst. Die Implementierung der entsprechenden Bibliothek wird zwar möglicherweise dein Gehirn schmelzen, aber wenn du die hast, steht dir nichts mehr im Wege. :P

[RustySpoon]

Das C++-Typsystem bietet aus Effizienzgründen zwar bewusst Schlupflöcher; wenn du diese aktiv nutzt, bist du jedoch selbst schuld (versehentlich geht nur mit unsicheren C-Style Casts, diese einfach nicht nutzen).

Naja, so echte "Macken" in der Sprache mein ich auch gar nicht. Mir ist auch durchaus bewusst, dass das C++-Typsystem immer noch eins der Besten ist. Mich ärgert vielmehr, das noch so viel mehr möglich sein könnte. Ich wundere mich z.B. regelmäßig, warum mein SAT-Solver sich plötzlich "komisch" verhält - sprich: langsamer als erwartet wird oder instabil ist, was die Laufzeiten angeht, aber eben nicht einfach falsch oder abstürzend. Bis ich dann dahinter komm, das wieder mal irgendwo ein short oder Ähnliches überläuft.
Und da kommste dann an den Punkt, den ich mein: Warum nutzt überhaupt jemand short? Beziehungsweise gibt es überhaupt andere integrale Typen außer int? Naja aus irgendwelchen abstrusen Effizienzgründen. Aber warum muss ICH mich um die korrrekte Auswahl kümmern? Warum kann ich nicht einfach sagen: "Hört mal her lieber Compiler und Laufzeitumgebung, ich muss hier irgendwie 'nen Wert zwischen 1 und 100 speichern, macht mir mal (Build I) das bezüglich Laufzeit Effizienteste daraus was geht und (Build II) etwas Sicheres, was mich informiert, wenn dieser Wertebereich wider Erwarten doch verlassen wird."
Nimm als anderes Beispiel einfach const. Braucht im Prinzip auch kein Mensch, trotzdem hilft es dir robusteren Code zu schreiben und Fehler zu vermeiden und dem Compiler effizienteren Maschinencode zu produzieren. Noch dazu trägt eine const-Variable eben auch eine inhärente Botschaft, für jemanden der den Code später vielleicht mal lesen, warten oder anderweitig nutzen muss. Da schlägt sich dann für mich wieder der Bogen zur Dokumentationsproblematik, weil ich eben nicht explizit dokumentieren muss, dass die Variable im Sinne des Systems nur "read-only" ist.

Tatsächlich ist C++11 wohl die erste gängige Sprache, in der du einen großen Teil dessen, was du hier beschreibst, sinnvoll selbst implementieren kannst. Die Implementierung der entsprechenden Bibliothek wird zwar möglicherweise dein Gehirn schmelzen, aber wenn du die hast, steht dir nichts mehr im Wege. :P

Und genau DAS lass ich nicht gelten. Klar kann ich das. Ich kann mir auch 'ne komplett eigene Super-Special-Awesome-Sprache definieren oder das Rad komplett neu erfinden. Aber das fällt eben eigentlich leider nicht in mein angestrebtes Tätigkeitsspektrum. ;) Ich bin theoretischer Informatiker und möchte Algorithmen einerseits so effizient wie möglich implementieren, andererseits so einfach und so klar wie möglich ausformulieren - was sich im gewissen Sinne mit dokumentieren überschneidet.

Und klar geht das "irgendwie". Aber einfach und vorallem elegant ist halt anders. Ich möchte mir ja eigentlich vorallem auch das Dokumentieren von Dingen sparen, die eh "intrinsisch" im Code stecken, bzw. die in meinem Kopf steckten als ich den Code geschrieben hab.

Aber genau das tu ich im Moment auch. Ich bastel beispielsweise gerade einen Wrapper für integrale Typen um einfach dieser lästigen Overflows mal Herr zu werden. Weiterhin hab ich gefühlt 2 dutzend Decorators rumfliegen, die einfach nur Vor- und Nachbedingungen sicherstellen und die Aufrufe delegieren. Aber die ersetzen halt auch nicht in dem Sinne Doku, wie das echte und sauber formulierbare Vor- und Nachbedingungen könnten. Dann spiel ich ernstlich mit dem Gedanken mir via libclang so 'ne Art extra C++-Präprozessor zu bauen, der mir DbC-Statements an verschiedenen Stellen im Code einwebt.

[dot]

Warum kann ich nicht einfach sagen: "Hört mal her lieber Compiler und Laufzeitumgebung, ich muss hier irgendwie 'nen Wert zwischen 1 und 100 speichern, macht mir mal (Build I) das bezüglich Laufzeit Effizienteste daraus was geht und (Build II) etwas Sicheres, was mich informiert, wenn dieser Wertebereich wider Erwarten doch verlassen wird."

Mit anderen Worten: Du willst einfach einen int.

Plain ints have the natural size suggested by the architecture of the execution environment; the other signed integer types are provided to meet special needs.

Range-Checking kannst du dir über templates selbst implementieren, sogar statisch über das Typsystem...

[CodingCat]

Und da kommste dann an den Punkt, den ich mein: Warum nutzt überhaupt jemand short? Beziehungsweise gibt es überhaupt andere integrale Typen außer int? Naja aus irgendwelchen abstrusen Effizienzgründen.

Die Effizienzgründe sind keineswegs abstrus. C++ ist und bleibt eine Produktionssprache mit dem Paradigma Zero Overhead. Dass gleichzeitig Sprachfeatures angeboten werden, von denen die meisten anderen gängigen Sprachen aktuell nur träumen können, ist das eigentlich Geniale. Wenn effizienzbedingte Features falsch eingesetzt werden, ist das nicht Problem der Sprache, sondern des Programmierers, der unbegründet short einsetzt. Sollten dir derlei Konvertierungen das Leben schwer machen, bietet dir aber wohl jeder vernünftige Compiler die Möglichkeit, in Debug-Builds auf Überläufe zu testen. In VC++ wäre das z.B. "Smaller Type Check" bzw. /RTCc.

Und genau DAS lass ich nicht gelten.

Warum kann ich nicht einfach sagen: "Hört mal her lieber Compiler und Laufzeitumgebung, ich muss hier irgendwie 'nen Wert zwischen 1 und 100 speichern, macht mir mal (Build I) das bezüglich Laufzeit Effizienteste daraus was geht und (Build II) etwas Sicheres, was mich informiert, wenn dieser Wertebereich wider Erwarten doch verlassen wird."

C++ ist eine universelle Bibliothekssprache. Die Sprache selbst versucht nach Möglichkeit alles anzubieten, was zur sinnvollen und effizienten Implementierung von anwendungsspezifischen Features erforderlich ist, ohne dabei selbst in ihrer Sprachspezifikation unerfüllbar umfangreich oder domänenspezifisch zu werden. Die Features, die du ansprichst, lassen sich mit Templates problemlos und elegant umsetzen. Deshalb wäre es grober Unfug, derlei Features fest in die Sprache aufzunehmen, zumal an integrale Datentypen gestellte Forderungen stets sehr anfwendungsspezifisch sind.

Nimm als anderes Beispiel einfach const. Braucht im Prinzip auch kein Mensch, trotzdem hilft es dir robusteren Code zu schreiben und Fehler zu vermeiden und dem Compiler effizienteren Maschinencode zu produzieren. Noch dazu trägt eine const-Variable eben auch eine inhärente Botschaft, für jemanden der den Code später vielleicht mal lesen, warten oder anderweitig nutzen muss. Da schlägt sich dann für mich wieder der Bogen zur Dokumentationsproblematik, weil ich eben nicht explizit dokumentieren muss, dass die Variable im Sinne des Systems nur "read-only" ist.

C++ bietet dir sein Typsystem und const ist Teil dieses Typsystems, genau wie Templates es sind. Mit Templates kannst du elegant Typen definieren und typsicher annotieren, in deinem Fall z.B. integer<1, 100>. Damit hast du gleichermaßen Typauswahl, Laufzeitchecks und Dokumentation, wie von dir beschrieben, mit minimalem Overhead. Wieso sollte derlei Funktionalität also in die Sprache aufgenommen werden? Dass Templates eine gewisse Barriere darstellen, bestreite ich nicht ...

Klar kann ich das. Ich kann mir auch 'ne komplett eigene Super-Special-Awesome-Sprache definieren oder das Rad komplett neu erfinden. Aber das fällt eben eigentlich leider nicht in mein angestrebtes Tätigkeitsspektrum. ;)

... aber diese Barriere ist weitaus geringer, als deine eigene domänenspezifische Sprache zu entwickeln. Klar muss derlei Bibliotheksfunktionalität irgendwann mal implementiert werden, genau wie derlei Sprachfeatures irgendwann mal implementiert werden müssten. Der Unterschied ist, die Bibliothek könntest du stemmen, eine vergleichbare eigene Sprache niemals. Andernfalls musst du eben warten, bis ein anderer dies für dich erledigt.

Schlussendlich ist das Funktionalität, die man in die Standardbibliothek aufnehmen könnte, und vielleicht in vielen Jahren auch wird. Dafür wird es jedoch zunächst einer erprobten Referenzimplementierung bedürfen, an der eine derartige Standardisierung ansetzen kann.

[CodingCat]

Und noch einige Dinge, die ich in deinem ursprünglichen Post vernachlässigt hatte, und dir hoffentlich helfen:

Ich dokumentier dann eben so Sachen wie: "forall variable: promising(variable) => score(variable) > 0 and not blocked(variable)". DAS möchte ich eigentlich als Invariante ausformulieren. Das Problem: Sowas geht in C++ halt höchstens über widerliche assert-Konstrukte, aber das bläht den Code auch extrem auf und im Zweifel kriegt man das auch nicht sauber abgeschaltet, weil man hier und da z.B. Hilfsvariablen benötigt

Dann machst du das wohl noch nicht optimal. ;) Dein Beispiel z.B. sollte im Optimalfall wie folgt aussehen:

Code: Alles auswählen

bool implies(bool a, bool b)
{
   return !a || b;
}

assert (
   std::all_of(
      variables.begin(), variables.end(),
      [](auto &variable) { return implies( promising(variable), score(variable) > 0 && !blocked(variable) ); }
   )
);

Mit etwas Template-Code bekommst du das sogar in folgende Form, wäre aber vermutlich eher verwirrend, vor allem wegen Operatorpräzedenzen.

Code: Alles auswählen

assert (
   std::all_of(
      variables.begin(), variables.end(),
      [](auto &variable) { return promising(variable) => (score(variable) > 0 && !blocked(variable)); }
   )
);

wenn ich z.B. überprüfen möchte, dass container.size() nach einmal aufrufen von push_back(...) wirklich 1 größer ist als vorher.

Bei Standardcontainern musst du das wohl nicht prüfen, weil dieses Verhalten ohnehin garantiert wird. Eine Hilfsvariable mit der alten Größe würde aber ziemlich sicher immer vom Compiler entfernt, sobald das assert verschwindet.

[RustySpoon]

Auch wenn ich nicht mit allen angeführten Kontra-Argumenten konform gehe, spar ich mir mal das weiter ins Detail zu gehen, weil der Thread hier sonst wahrscheinlich noch 5x aufgeteilt werden muss. ;)

Aber ganz allgemein: Das waren Beispiele, die mir tagtäglich so unterkommen, die zum Teil auch schon (wenig elegant) gelöst wurden, aber deren ideale, fiktive und generalisierte Lösung verdeutlichen soll, worum es mir eigentlich geht. Aber es bleiben eben Beispiele, und allein der Umstand, das hier jetzt diverse, sehr unterschiedliche Lösungen (extra Libraries, Compilerflags, DSLs, ...) für die angesprochen Probleme gekommen sind, verdeutlicht doch, dass da irgendwie was Generelleres fehlt.

Irgendwie driftet mir das auch etwas zusehr in eine C++-Pro/Con-Diskussion ab. Versteht mich nicht falsch, ich benutz die Sprache ja auch gerade wegen ihrer Multi-Paradigmen-Fähigkeit und "Zero Overhead" und mir ist durchaus bewusst, dass C++ aus diesen Gründen gewisse semantische/deklarative Features nicht anbieten kann. Hab ich aber auch nicht verlangt oder gar behauptet, dass sie das tun müsste um eine Daseins-Berechtigung zu haben. Im Gegenteil, ich benutz die Sprache ja aus eben diesen Gründen und gerade WEIL ich mir eben, wenn der Schmerz nicht mehr auszuhalten ist so Sachen wie Range-Checks implementieren kann. ;)

Aber das wiederrum bedeutet nicht, sich keine Gedanken darüber machen zu dürfen, warum man gewisse Dinge umständlich lösen muss oder zu erörtern, wie eine vermeintlich bessere Lösung aussehen könnte.

Um nochmal die Diskussion zurück auf die ursprüngliche Bahn zu lenken, meine Thesen:

• Viel Dokumentation, die wir so alltäglich schreiben müssen, wäre nicht notwendig, wenn unsere Sprachen ein anderen Grad an Spezifikation sauber im Code ermöglichen würden - konkret stelle ich mir da etwas vor, was in die Richtung "Design by Contract" geht. Anders ausgedrückt: Weniger technnisch-orientierte, dafür mehr deklarative Konstrukte.
• Neben einer klareren und konsistenteren Dokumentation, sehe ich als zusätzliche Boni einer solchen (fiktiven) Sprache: (a) Durch bessere Deduktionsmöglichkeiten während der Kompilierung Fehler im Voraus zu vermeiden und (b) zusätzliche Optimierungspotenziale für den Compiler.

[CodingCat]

Irgendwie driftet mir das auch etwas zusehr in eine C++-Pro/Con-Diskussion ab.

Das war aber zu keiner Zeit meine Intention, vielmehr ging es mir um deine konkreten Aussagen zu C++. Dass ich von C++ bei weitem nicht nur begeistert bin, wurde in diesem Forum aber an anderer Stelle schon oft genug deutlich. :mrgreen:

Auch wenn ich nicht mit allen angeführten Kontra-Argumenten konform gehe, spar ich mir mal das weiter ins Detail zu gehen, weil der Thread hier sonst wahrscheinlich noch 5x aufgeteilt werden muss. ;)

Schade, denn gerade jetzt wird es doch interessant. Deshalb gebe ich dir einfach mal frech weiter Diskussionsanregung. ;)

Aber ganz allgemein: Das waren Beispiele, die mir tagtäglich so unterkommen, die zum Teil auch schon (wenig elegant) gelöst wurden, aber deren ideale, fiktive und generalisierte Lösung verdeutlichen soll, worum es mir eigentlich geht. Aber es bleiben eben Beispiele, und allein der Umstand, das hier jetzt diverse, sehr unterschiedliche Lösungen (extra Libraries, Compilerflags, DSLs, ...) für die angesprochen Probleme gekommen sind, verdeutlicht doch, dass da irgendwie was Generelleres fehlt.

Das ist genau die Frage. Hierfür müsstest du allerdings mal von deinen vergleichsweise problemfreien Beispielen weggehen und konkrete Vorschläge für solche weithin nützlichen Sprachfeatures machen. Insbesondere sollten diese in Sprachform einen wesentlichen Vorteil gegenüber einer Bibliotheksform aufweisen, ohne dabei in eine domänenspezifische Sprache abzudriften.

Um nochmal die Diskussion zurück auf die ursprüngliche Bahn zu lenken, meine Thesen:

• Viel Dokumentation, die wir so alltäglich schreiben müssen, wäre nicht notwendig, wenn unsere Sprachen ein anderen Grad an Spezifikation sauber im Code ermöglichen würden - konkret stelle ich mir da etwas vor, was in die Richtung "Design by Contract" geht. Anders ausgedrückt: Weniger technnisch-orientierte, dafür mehr deklarative Konstrukte.
• Neben einer klareren und konsistenteren Dokumentation, sehe ich als zusätzliche Boni einer solchen (fiktiven) Sprache: (a) Durch bessere Deduktionsmöglichkeiten während der Kompilierung Fehler im Voraus zu vermeiden und (b) zusätzliche Optimierungspotenziale für den Compiler.

Klingt spannend, auch hier wären konkrete Ideen (oder auch Verweise auf andere Sprachen) interessant.

[pUnkOuter]

Ich find's ja immer irgendwie amüsant, wie sich die Leute über "alles muss dokumentiert werden" vs. "nichts muss dokumentiert" werden in die Haare kriegen. Meines Erachtens ist das schlicht und einfach eine Frage, was die jeweilige Sprache an Abstrahierung und High-Level-Features zu bieten hat.

Ganz genau. Dokumentation ist nur dann nötig, wenn davon ausgegangen werden muss, dass ein Programmierer, der da noch was ändern muss, den Code nicht verstehen wird. Ob das an mangelnden Sprachfeatures liegt, oder ob schlechter Code wegen fehlender Sprachbeherrschung geschrieben wird, ist dabei eigentlich egal.

Ich ärgere mich jedenfalls immer, wenn ich an eine Stelle komme, die ich auch nach genauem Lesen nicht verstehe. Dann versuche ich zuerst, das neu zu schreiben, was leider nicht immer gelingt, und dann halt manchmal doch in einem Kommentar mündet.

[BeRsErKeR]

Codekommentare sind schon hilfreich. In einer perfekten Welt in der Code selbsterklärend und übersichtlich ist vielleicht nicht, aber es gibt meiner Erfahrung nach keinen Programmierer der das zu 100% hinbekommt.

Eine Dokumentation (mit doxygen und Co) finde ich hingegen nur dann sinnvoll, wenn man wirklich ein Projekt dokumentiert (Engine, Library, etc). Ansonsten finde ich es eher hinderlich, da man mehr Zeit mit dokumentieren als mit implementieren verbringt. Zumal sehr häufig dann doch bestimmte Funktionen, Parameter oder Rückgabewerte selbsterklärend sind. Man muss nicht jeden Pups dokumentieren.

Ich habe mal an einem sehr großen Projekt mitgearbeitet. Es gab nicht eine Zeile Kommentar oder Dokumentation und der Code war dennoch recht einfach zu lesen, da man sich auf bestimmte Konventionen geeinigt hat und sehr viele kleine Module hatte. Es geht also schon ganz ohne, aber im Allgemeinen sind Kommentare schon eine gute Idee. Eine Dokumentation wie gesagt eher selten.

[Jonathan]

Aber bei sowas finde ich es gar nicht schlecht, zumindest ein paar Texte zu haben, die die groben Konzepte erklären. Welche Klassen wichtig sind und wie sie zusammen spielen und so.

[jumphigh]

Das war aber zu keiner Zeit meine Intention, vielmehr ging es mir um deine konkreten Aussagen zu C++. Dass ich von C++ bei weitem nicht nur begeistert bin, wurde in diesem Forum aber an anderer Stelle schon oft genug deutlich. :mrgreen:

Wenn dir C++ nicht passt, musst du es halt mit Ada versuchen. Zumindest kann diese Sprache Integer-Subtypen definieren und ein typedef ist nicht nur ein Alias, sondern ein echter, unabhängiger Typ. Scheint beim MIlitär und an Unis - also dein Metier ;-) - beliebt zu sein.

MfG
Andreas