Wie dokumentiert ihr?

Schon klar. Drum frag ich ja, wie das andere so machen.

Im Moment mach ich es so, dass ich mit Doxygen nur Zeug dokumentiere, das für den Anwender interessant ist. Technische Details etc. dokumentiere ich mit normalen Kommentaren.

dokuLer schrieb:

Eigentlich bräuchte ich also 2 Dokus: Eine für reine Anwender und eine für Entwickler. Wie macht ihr das?

Ich schreibe Entwickler-"Interna" in die normale Doku, mit dem Hinweis, dass es eigentlich nur für Entwickler interessant ist. Besser wäre es wohl solche Bereiche zu markieren und mit einem Tool zu löschen um die Anwenderdoku zu generieren. Kann doxygen sowas nicht schon von Haus aus (weiss es wirklich nicht)? Ansonsten könntest ja mal die Entwickler frage, ob sie sowas nicht umsetzen wollen. Das könnte mehrere Leute interessieren.

dokuLer schrieb:

Das Dilemma: Wenn ich solche Details dokumentiere, könnte es den Anwender meiner Lib verwirren, denn eigentlich braucht er das eigentlich nicht wissen.
Andererseits wenn ich es nicht dokumentiere, dann verstehe ich nächste Woche meinen eigenen Code schon nicht mehr.

Programmierst du mit C++?

WhatIsItGoodFor schrieb:

dokuLer schrieb:

Das Dilemma: Wenn ich solche Details dokumentiere, könnte es den Anwender meiner Lib verwirren, denn eigentlich braucht er das eigentlich nicht wissen.
Andererseits wenn ich es nicht dokumentiere, dann verstehe ich nächste Woche meinen eigenen Code schon nicht mehr.

Programmierst du mit C++?

libs in C++, das wäre aber eine ganz schlechte Idee.

Gregor

dokuLer schrieb:

Schon klar. Drum frag ich ja, wie das andere so machen.

Du hast volkard nicht verstanden. Das Problem ist da nicht die Dokumentation. In der Dokumentation steht drin, was ein Code macht. Das weißt Du aber nach einer Woche eh noch. Wenn Du Deinen eigenen Code unter solchen Bedingungen nicht verstehst, dann liegt das an der Art, wie Du programmierst und nicht daran, wie Du die Dokumentation schreibst.

Du hast unlesbaren Code geschrieben. Das ist das Problem. Und es erfordert definitiv eine ganze Menge Erfahrung, gut lesbaren Code zu schreiben. Guck Dir den Code mal an und überleg Dir, was daran das Problem sein könnte. Oder poste hier mal'n paar hundert Zeilen Code und frag nach Verbesserungsvorschlägen.

dokuLer schrieb:

Eigentlich bräuchte ich also 2 Dokus: Eine für reine Anwender und eine für Entwickler. Wie macht ihr das?

klar, anwender kriegen ein user manual, wo alles ausführlich drinsteht, was man machen kann, konzepte, beispiele usw. entwickler kriegen zusätzlich noch doku, die aus kommentaren im quelltext erzeugt wurde (z.b. mit sowas wie doxygen), die zusätzliche details zum weiterbasteln am code enthält. entwickler müssen also beides lesen, das user manual ist aber das gehaltvollere davon.

rüdiger

Tim schrieb:

Kann doxygen sowas nicht schon von Haus aus (weiss es wirklich nicht)?

http://www.stack.nl/~dimitri/doxygen/config.html#cfg_internal_docs

Gregor schrieb:

Du hast volkard nicht verstanden. Das Problem ist da nicht die Dokumentation. In der Dokumentation steht drin, was ein Code macht. Das weißt Du aber nach einer Woche eh noch. Wenn Du Deinen eigenen Code unter solchen Bedingungen nicht verstehst, dann liegt das an der Art, wie Du programmierst und nicht daran, wie Du die Dokumentation schreibst.

Du hast unlesbaren Code geschrieben. Das ist das Problem. Und es erfordert definitiv eine ganze Menge Erfahrung, gut lesbaren Code zu schreiben. Guck Dir den Code mal an und überleg Dir, was daran das Problem sein könnte. Oder poste hier mal'n paar hundert Zeilen Code und frag nach Verbesserungsvorschlägen.

Komm mal wieder runter von deinem Arroganztripp. Mag ja sein, dass du vielleicht nur Trivialcode geschrieben hast, aber wenns in den mathematischen Bereich geht, dann entsteht sehr schnell komplexer Code, den man nach einiger Zeit selber nicht mehr schnell nachvollziehen kann (z.B. Reindizierung eines Vertexgitters bei LOD Algorithmen - das ist grausiges Integerrumgeschiebe mit zig Modulos usw.)
So Quatsch a la "wenn Code nicht selbstbeschreibend ist, ist er mies" kommt meistens von Java Leute, die nur Highlevel/Business Code schreiben.

@+fricky: Sehe ich auch so. Nicht um sonst hat große Software oft extra noch ein "Dev-Kit" mit eigener Developer Docu.

@rüdiger: Danke. Dann kann das Doxygen offenbar doch bereits.

Gregor

dokuLer schrieb:

Komm mal wieder runter von deinem Arroganztripp. Mag ja sein, dass du vielleicht nur Trivialcode geschrieben hast, aber wenns in den mathematischen Bereich geht, dann entsteht sehr schnell komplexer Code, den man nach einiger Zeit selber nicht mehr schnell nachvollziehen kann (z.B. Reindizierung eines Vertexgitters bei LOD Algorithmen - das ist grausiges Integerrumgeschiebe mit zig Modulos usw.)
So Quatsch a la "wenn Code nicht selbstbeschreibend ist, ist er mies" kommt meistens von Java Leute, die nur Highlevel/Business Code schreiben.

Hi.

Es ist Dir vielleicht nicht aufgefallen, aber ich habe in keinster Weise gesagt, dass ich gut lesbaren Code produziere. Mir ist sehr klar, dass das schwierig ist und wenn Du ein kompliziertes Anwendungsgebiet hast, dann ist es noch viel schwieriger, aber auch nicht unmöglich. Gut lesbarer Code sollte aber in jedem Fall ein Ziel beim Programmieren sein und wenn man sich Dein Problem anhört, dann ist es offensichtlich, dass Du Deinen eigenen Code nicht lesen kannst. Ich meine, nach einer einzigen Woche weißt Du noch ganz genau, was Dein Code macht und Du kennst auch die verwendeten Verfahren noch genau. Du hast nach einer Woche noch wesentlich mehr Wissen von Deinem Code, als man durch die beste Doku bekommen könnte. Wie soll die Lösung für Dein Problem dann in der Doku liegen? Es ist offensichtlich, dass Du in erster Linie mit dem Lesen des Codes Probleme hast. Also solltest Du auch beim Code ansetzen, um Dein Problem zu lösen.

Mein Beitrag oben war übrigens in keinster Weise beleidigend gemeint. Sorry, falls das so rübergekommen ist. Aber nach dem, was Du sagst, sehe ich das Problem einfach an ganz anderer Stelle als Du.

Walli

Ausserdem kann man auch komplexen Code schön schreiben. Man hat nur meistens keinen Bock dazu, weil es viel interessanter ist, das eigentliche Problem zu lösen als einen Schönheitspreis für den Code zu gewinnen .