Richtige Dokumentation

[Meeresgott]

Hallo liebes Forum,

ich programmiere schon seit längerem, allerdings nur relativ kleine Programme.
Nun habe ich ein nie fertiggestelltes Programm wieder in Angriff genommen und sehe den Wald vor lauter Bäumen nicht. 🙁

Ich bin auf der Suche nach einem Tool mit dem ich an meinen Code Hinweise hinterlassen und die Wichtigkeit oder ähnliches.

Nachdem ich dann den Code durchgearbeitet habe, möchte ich am liebsten in einer GUI sehen, wo was zu machen ist und wie dringend es ist, dass ich diese Änderungen vornehme.

Es ist egal, ob es ein Plugin ist oder ein externes Programm (Am liebsten wäre mir ein Plugin für Netbeans).

Die Lösungen, die ich finden konnte waren mit einem Server auf den der Code hochgeladen wird und dann konnte ich mit einer Art Ticket-System anzeigen, was noch zu tun ist. Finde ich gar nicht so schlecht aber bitte ohne einen Server aufsetzen zu müssen.

Hoffentlich könnt ihr mir da helfen 🙂
Da dies eher ein Anfänger-Thema ist, habe ich es hier rein gestellt.

LG

 

[Robat]

Hier vielleicht mal eine kleine Anregung von mir:
Ich überlege mir vorher was alles ins Programm rein soll, mache mir extern (in dem Programm deiner Wahl) eine TODO Liste, wo ich dann abhake was ich schon habe.
Im Code selber kannst du ja mit //TODO Kommentaren arbeiten. Da gibts für Netbeans soweit ich weiß Tools um sich das schön in einem Fenster anzeigen zu lassen.

Gruß Robert

 

[VfL_Freak]

Moin,

Ich bin auf der Suche nach einem Tool mit dem ich an meinen Code Hinweise hinterlassen und die Wichtigkeit oder ähnliches.

Was meinst Du mit "Tool" ??
Warum kommentierst Du nicht einfach Deinen Code entsprechend aus??

VG Klaus

 

[marlo]

moin,
spontan fällt mir dazu javadoc ein...und wie VFL schon sagte - kommentieren..
mfg martin

 

[stg]

Die Lösungen, die ich finden konnte waren mit einem Server auf den der Code hochgeladen wird und dann konnte ich mit einer Art Ticket-System anzeigen, was noch zu tun ist. Finde ich gar nicht so schlecht aber bitte ohne einen Server aufsetzen zu müssen.

Kann doch trotzdem lokal bei dir auf der Maschine laufen. Schau dir z.B. mal die Produkte von Atlassian an, da ist für Alle(s) was dabei. In deinem Fall etwa Jira.

Im Code selber kannst du ja mit //TODO Kommentaren arbeiten. Da gibts für Netbeans soweit ich weiß Tools um sich das schön in einem Fenster anzeigen zu lassen.

Extra Plugins oder dergleichen brauctht es dafür nicht einmal. NetBeans erkennt solche Kommentare automatisch und man kann sie sich als "Action Items" anzeigen lassen. Man sollte mMn aber nur mäßig davon gebrauch machen und lieber eine Baustelle nach der anderen fertigstellen, sofern möglich.

Warum kommentierst Du nicht einfach Deinen Code entsprechend aus??

Nicht gebrauchter Code wird nich auskommentiert, sondern gelöscht. Auch wenn man ihn später vielleicht doch noch verwenden möchte. Ist das der Fall, dann schaut man in einen früheren Commit seiner Versionsverwaltung und holt ihn zurück. Solche Artefakte stören nur beim lesen und man ist erstaunt, wie selten man tatsächlich einmal gelöschten Code doch noch einmal braucht.

Es ist egal, ob es ein Plugin ist oder ein externes Programm (Am liebsten wäre mir ein Plugin für Netbeans).

Den Hinweis mit den //TODO Kommentaren hast du ja schon bekommen. Alternativ, wenn es kleine Projekte sind und du alleine daran arbeitest, kannst du auch einfach eine handschriftliche Liste, Excel-Mappe oder sonst was führen. Ich schreib mir (zuätzlich zu genannten Variante) allen S***** (auf Papier) auf, der mir einfällt, sobald es mir ein/auffällt, sonst vergess ich eh mindestens die Hälfte.

 

[stg]

Die Lösungen, die ich finden konnte waren mit einem Server auf den der Code hochgeladen wird und dann konnte ich mit einer Art Ticket-System anzeigen, was noch zu tun ist. Finde ich gar nicht so schlecht aber bitte ohne einen Server aufsetzen zu müssen.

Kann doch trotzdem lokal bei dir auf der Maschine laufen. Schau dir z.B. mal die Produkte von Atlassian an, da ist für Alle(s) was dabei. In deinem Fall etwa Jira.

Im Code selber kannst du ja mit //TODO Kommentaren arbeiten. Da gibts für Netbeans soweit ich weiß Tools um sich das schön in einem Fenster anzeigen zu lassen.

Extra Plugins oder dergleichen brauctht es dafür nicht einmal. NetBeans erkennt solche Kommentare automatisch und man kann sie sich als "Action Items" anzeigen lassen. Man sollte mMn aber nur mäßig davon gebrauch machen und lieber eine Baustelle nach der anderen fertigstellen, sofern möglich.

Warum kommentierst Du nicht einfach Deinen Code entsprechend aus??

Nicht gebrauchter Code wird nich auskommentiert, sondern gelöscht. Auch wenn man ihn später vielleicht doch noch verwenden möchte. Ist das der Fall, dann schaut man in einen früheren Commit seiner Versionsverwaltung und holt ihn zurück. Solche Artefakte stören nur beim lesen und man ist erstaunt, wie selten man tatsächlich einmal gelöschten Code doch noch einmal braucht.

Es ist egal, ob es ein Plugin ist oder ein externes Programm (Am liebsten wäre mir ein Plugin für Netbeans).

Den Hinweis mit den //TODO Kommentaren hast du ja schon bekommen. Alternativ, wenn es kleine Projekte sind und du alleine daran arbeitest, kannst du auch einfach eine handschriftliche Liste, Excel-Mappe oder sonst was führen. Ich schreib mir (zuätzlich zu genannten Variante) allen S***** (auf Papier) auf, der mir einfällt, sobald es mir ein/auffällt, sonst vergess ich eh mindestens die Hälfte.

 

[VfL_Freak]

Moin,

Nicht gebrauchter Code wird nich auskommentiert, sondern gelöscht. Auch wenn man ihn später vielleicht doch noch verwenden möchte. Ist das der Fall, dann schaut man in einen früheren Commit seiner Versionsverwaltung und holt ihn zurück. Solche Artefakte stören nur beim lesen und man ist erstaunt, wie selten man tatsächlich einmal gelöschten Code doch noch einmal braucht.

Oops, sprachliches Missverständnis 😱 mea maxima culpa !!
Ich meinte mit 'auskommentieren' nicht das Löschen von Code, sondern das Schreiben sinniger Kommentare im Code 😎

VG Klaus

 

[Meeresgott]

@VfL_Freak Der Kommentar muss aber auch ertsmal gefunden werden. Wird dieser nicht gefunden, so bringt mir der beste Kommentar nichts - Dafür möchte ich eine solche Übersicht haben.

@stg ich bin aus mangel an Arbeitsspeicher sehr gebunden. Deshalb möchte ich so wenig im hintergrund laufen haben wie möglich. Wo ein Server läuft muss dann zwangsläufig auch ein Client laufen.
Ich bevorzuge eine Zentralle Stelle an der ich Sachen ablegen kann, die noch zu tun sind. Finde ich übersichtlicher als alles Aufteilen in Papier, Excel und Netbeans (//TODO) Listen.

Die //TODO Funktion kannte ich noch gar nicht auch werde ich mir Jira mal anschauen.
Vielleicht Hilft euch die Dimension des Projektes es sind ca. 110.000 Zeilen Code aufgeteilt in ein bisschen mehr als 200 Klassen. Demenstrpechend ist ein Navigator zum ausbessern wesentlich bequemer als nur das Grobe Thema aufzuschreiben, da ich mich sonst durch Klassen wühlen müsste um das Kommentar zu finden.

LG

 

[marlo]

und was spricht dann dagegen eine javadoc zu erstellen?
wie das geht weisst bestimmt?
/**
* text blablub
*/

vor der main zb um zu schreiben was du bauen willst
vor den jeweiligen methoden, was sie machen, was noch fehlt...

dann die doc erstellen und du hast eine html-seite in deinem src-ordner des projekts..einfach mit browser öffnen und lesen..das in verbindung mit einer todo-liste in der doc sollte doch passen
mfg martin

 

[Meeresgott]

@marlo Eine Dokumentation habe ich schon gemacht. Aber habe ich da nicht dasselbe Problem, dass ich dann jede Klasse (zwar in der Doc) durchschauen muss und nicht auf einen Blick erkennen kann was wo zu tun ist ?

Lg Sebastian

 

[mrBrown]

Es gibt auch gehostete Ticketsysteme, die man kostenlos nutzen kann - im Zweifel langt sogar der Issuetracker von github.

Deshalb möchte ich so wenig im hintergrund laufen haben wie möglich. Wo ein Server läuft muss dann zwangsläufig auch ein Client laufen.

Der Client ist in dem Fall der Browser und eingeschränkt die IDE, und beides dürfte ja sowieso laufen 😉

Ich bevorzuge eine Zentralle Stelle an der ich Sachen ablegen kann, die noch zu tun sind. Finde ich übersichtlicher als alles Aufteilen in Papier, Excel und Netbeans (//TODO) Listen.

Erfahrungsgemäß klappt es nie mit einer zentralen Stelle, das läuft immer auf mehrere hinaus (die dann aber auch unterschiedliche Dinge abdecken). Bei mir aktuell UserStory + Tasks + Notizen mit sonstigen Todos + TODO/HACK/FIXME im Code

Vielleicht Hilft euch die Dimension des Projektes es sind ca. 110.000 Zeilen Code aufgeteilt in ein bisschen mehr als 200 Klassen.

110.000 Zeilen ohne jegliche Projektplanung? Respekt

 

[Meeresgott]

Es gibt auch gehostete Ticketsysteme, die man kostenlos nutzen kann - im Zweifel langt sogar der Issuetracker von github.

Das heißt jemand anderer hat kompletten Zugriff auf meinen Quellcode ? - Ich weiß ein bisschen Paranoid.

Wahrscheinlich muss ich mir auch eine Art Mittelweg ausdenken. Mir ist wie gesagt nur wichtig, dass ich Dinge die ich an meinen Code schreibe in einer Übersicht sehe.

110.000 Zeilen ohne jegliche Projektplanung? Respekt

Danke! Aber war gar nicht ohne jegliche Plaung. Hatte EA benutzt um zu wissen, welche Pattern ich brauche und dort dierekt die Dokummentation angefangen. Zudem konnte ich mich zumindest ein wenig an ähnlichen "Historisch gewachsenen Projekten" die das Porjekt ursprünglich ersetzen sollte Orientieren. Nur blöd, wenn man in der Mitte aufhört und man 6 Monate später nicht mehr weiß was man zu tun hatte.

 

[mrBrown]

Das heißt jemand anderer hat kompletten Zugriff auf meinen Quellcode ? - Ich weiß ein bisschen Paranoid.

Nein, das geht auch alles privat mit Login 😉

 

[JStein52]

Nein, das geht auch alles privat mit Login

Aber das ist dann alles (genau so wie Jira und ähnliche) mit Interkontinentalraketen auf Spatzen geschossen. Welchen Mehrwert bietet das für ihn gegenüber einer schlichten Exceltabelle ?

 

[Meeresgott]

gegenüber einer schlichten Exceltabelle

Wie sähe diese denn aus ?

Stelle mir nur sowas vor mit den spalten Wichtigkeit, Kommenatar, Klasse, Zeile

 

[JStein52]

mit den spalten Wichtigkeit, Kommenatar, Klasse, Zeile

Exakt. Aber schau dir dir trotzdem das Thema "ActionItem" (//TODO) bei NetBeans noch an, das wäre für mich der Favorit, wird aber unhandlich wenn du zu viele ActionItems anlegst. Das ist mehr für kurzfristige Themen gut.

 

[mrBrown]

Aber das ist dann alles (genau so wie Jira und ähnliche) mit Interkontinentalraketen auf Spatzen geschossen. Welchen Mehrwert bietet das für ihn gegenüber einer schlichten Exceltabelle ?

Warum sollte man nicht ein Planungstool zum Planen nutzen? Das dürfte in den meisten Fällen sogar weniger Aufwand als ne eigene Exceltabelle sein...

Auf die schnelle: vernünftiges GUI, Referenzen untereinander, referenzieren mit Commits, Vernünftiges gruppieren und sortieren, je nach Tool auch noch mit Sprint/Meilensteinplanung, ...
Ja, kann man alles irgendwie mit Excel nachbauen - aber will man das auch?

 

[mrBrown]

Aber das ist dann alles (genau so wie Jira und ähnliche) mit Interkontinentalraketen auf Spatzen geschossen. Welchen Mehrwert bietet das für ihn gegenüber einer schlichten Exceltabelle ?

Warum sollte man nicht ein Planungstool zum Planen nutzen? Das dürfte in den meisten Fällen sogar weniger Aufwand als ne eigene Exceltabelle sein...

Auf die schnelle: vernünftiges GUI, Referenzen untereinander, referenzieren mit Commits, Vernünftiges gruppieren und sortieren, je nach Tool auch noch mit Sprint/Meilensteinplanung, ...
Ja, kann man alles irgendwie mit Excel nachbauen - aber will man das auch?

 

[JStein52]

Ich bin auf der Suche nach einem Tool mit dem ich an meinen Code Hinweise hinterlassen und die Wichtigkeit oder ähnliches.

vernünftiges GUI, Referenzen untereinander, referenzieren mit Commits, Vernünftiges gruppieren und sortieren, je nach Tool auch noch mit Sprint/Meilensteinplanung, ...

Irgendwie seid ihr in verschiedenen Welten. Ich habe nicht gesagt dass es nicht geht sondern dass es overkilled ist !

 

[mrBrown]

Das ist das schon genannte TODO, was ganz ohne irgendwas externes funktioniert 😉
Aber die Frage und die 110.000 Zeilen klingen nicht danach, als ob das ausreichend wäre...

 

[JStein52]

Das ist das schon genannte TODO

Genau. Guckst du Post #16 ! Und 110.000 Zeilen Code heisst ja nicht dass er ständig einigen tausend TODO's hinterher läuft. Mal davon abgesehen dass du diese in NetBeans auch noch filtern und sortiere könntest. Aber ich habe ja schon geschrieben, bei zu vielen wird es unhandlich. Das muss der TE beurteilen.

 

[Meeresgott]

Irgendwie seid ihr in verschiedenen Welten.

Kann gut sein 🙂 Aber ich finde Professionelles Arbeiten macht immer Sinn.
Doch hier scheint mir das auch ein wenig übertrieben (zumindest von meinem jetzigen Standpunkt aus)
Nichts gegen @mrBrowns Lösung, doch ich werde erstmal mit dem TODO arbeiten.

Falls es nicht ausreicht und ich durch zu viele TODOs verwirrt werde, werde ich auf die größere Variante umsteigen müssen. Ich habe ja den "Luxus" als Privater umsteigen zu können wann immer ich mag.

Vielen Dank für eure Antworten! Sie haben mir sehr geholfen 😀

LG
Sebastian

 

[marlo]

@Meeresgott

Eine Dokumentation habe ich schon gemacht. Aber habe ich da nicht dasselbe Problem, dass ich dann jede Klasse (zwar in der Doc) durchschauen muss und nicht auf einen Blick erkennen kann was wo zu tun ist ?

zuerst muss ich gestehen, dass ich nur gelesen hatte, dass du "kleine" programme schreibst, 110.000 zeilen mit 200+ klassen sind für mich jenseits dessen, was ich "klein" nennen würde, auch wenn es nur ein bruchteil dessen ist, was ein betriebssystem oder sap so als codezeilen hat 😉
aber zurück zum thema .
jain
es kommt drauf an, wie du und wo du kommentierst.
ich schreib bei meinem kleinen progrämmchen über der jeweiligen klasse, was sie machen soll, wofuer sie da ist was bereits umgesetzt ist, was noch fehlt, und manchmal auch noch spontan was man noch hinzufuegen koennte...

und das kann ich mir dann in der javadoc klassenzusammenfassung ansehen und dann von da aus in die enstprechende klasse und die methodenbeschreibungen gehen um eventuell weitere informationen auszulesen. ich muss mich allerdings korrigieren - es ist nnicht nur eine html-seite, sondern mehrerere. bei meinem kleinen autoverwaltungsprogrämmchen mit bis jetzt 5 klassen sinds schon 8 seiten und liegen nicht im src sondern im dist-ordner..
und in der javadoc kannst du ja auch html-befehle benutzen um wichtiges hervorzuheben zb.
da könntest du dann zb auch eine tabelle oder liste einfuegen..


ich persönlich benutze lieber so wenig tools wie möglich und halte auch alles lieber lokal. für mich ist das noch ausreichend. um ehrlich zu sein, all die andren genannten tools kenn ich gar nicht ..bin ja auch noch n newb in java und froh, dass ich mittlerweile mit der jdoc soweit erstmal alles nötige abdecken kann 😉

wobei ich bisher noch nichtmal mit den javadoc tags arbeite, @see und @Link wirken um diese uhrzeit ganz interessant...

naja
mfg martin

ps: der tabellencode ist nur fix copy ´n paste aus einem selfhtml beispiel in den javadoc kommentar eingefügt
könnte man auch schöner darstellen..