Wie dokumentiert ihr euren Quellcode bzw. bearbeitete Tickets

[gimbo]

Tja, ich denke die Frage ist gar nicht so schwierig, allerdings wird das bei uns das Thema seit jeher stiefmütterlich behandelt. Bei vielen Firmen wird gar nicht dokumentiert, bei uns findet eher eine wildwüchsige Überkontrolle statt.

Der Entwickler bearbeitet bei uns ein Ticket in der Reklamationserfassung und trägt es dort als erledigt mit Kommentar ein. Danach schreibt er einen Eintrag für das Anwenderprotokoll (also was der Anwender bei neuen Versionen erhält) und einen Eintrag für das Developerprotokoll (für den Tester). Dazu macht er noch einen Eintrag in der Zeiterfassung, was er gemacht hat. Außerdem gibt der Entwickler nochmal mündlich Rückmeldung und gegebenenfalls muss er auch dem Kunden nochmal Bescheid geben. Darüber hinaus muss natürlich der Quellcode kommentiert werden.

Es sind also für jede(!) noch so banale Änderung am Programm an 3 bis 5 Stellen Kommentare zu hinterlassen. Ich finde das unheimlich umständlich, zeitaufreibend und es wird von mir daher meist nur lückenhaft durchgeführt, weil eine zentrale Stelle zur Dokumentation fehlt. Ich habe wirklich kein Problem meine Tätigkeiten zu dokumentieren, aber wenn es in Schikane ausartet, dann läuft etwas falsch.

Wie macht ihr das? Benutzt ihr JIRA, OTRS, Polarion oder dergleichen? Führt ihr die Ticket-Nr. im Quellcode mit? Werden die Protokolle für ein Release automatisch durch das Ticketsystem oder Bug-Tracking-System generiert? Gibt es eine Integration mit der Versionsverwaltung? Wird der Lebenszyklus einer Softwareänderung tatsächlich auch informationstechnisch abgebildet?

Am liebsten würde ich unser jetziges System auf links ziehen. Ich würde einfach gerne wissen, wie das bei anderen so abläuft.

[axxis]

Für Tickets die unsere Entwicklung betreffen: MantisBT

Quellcode wird auch direkt kommentiert (also im Code, nicht irgendwo außerhalb)

Zeiterfassung ist bei uns keine Vorgabe, das würde mich persönlich auch stören.

Dazu muss ich aber sagen, dass wir inhouse tätig sein, d.h. unsere Kollegen sind unsere "Kunden"

[Pixie]

Bei uns können Mantis und die Zeiterfassung miteinander. Wenn eine Tätgkeit also ticketbezogen war, wird nur die Ticketnummer eingetragen.

Wäre auch ausbau- und verbesserungsfähig.

[gimbo]

Ja, grundsätzlich bin der Meinung, dass Einträge im Bug-Tracking-System (bei uns: Reklamationserfassung) auch als Einträge in der Zeiterfassung angesehen werden sollten. Man könnte dort auch direkt Plan- und Ist-Aufwände eintragen und damit dann eben Kalkulationen anstellen (z.B. Aufwand für ein Release, Abweichungen in der Planung).

In der Zeiterfassung wird nicht das gleiche eingetragen wie im Bug-Tracking-System, sondern eher als Zusammenfassung. Man könnte auch per Copy&Paste arbeiten, aber das ist natürlich trotzdem sehr lästig und ganz einfach überflüssig (zumal Reklamationserfassung und Zeiterfassung ohnehin in einem Programm vereint sind).

[MartinSt]

Neben den Kommentaren im Quellcode nutzen wir git und übergeben die dortigen commit-Kommentare an bugzilla als Bugtracker.

Demnächst wird eine ähnliche Anbindung von auch zu otrs entstehen.

Gruß Martin

[gimbo]

Wie wird das übergeben? Werden die Kommentare in einem bestimmten Format (javadoc o.ä.) angegeben und dann durch ein Tool in den Bugtracker rübergeschaufelt? Wird dazu die Ticket-Nr. im Quellcode hinterlegt?

[MartinSt]

@gimbo

wir haben ein selbstgestricktes Script, das git-commit der Form: Bugfix: 4711 Text

erkennt und damit den Bug 4711 auf erledigt setzt und "Text" als Erledigungskommentar im Bugzilla einträgt

Direkte Zugriffe auf den Code bzw. Kommentare im Code erfolgen hierbei nicht.

Gruß Martin

[metux]

Der Entwickler bearbeitet bei uns ein Ticket in der Reklamationserfassung und trägt es dort als erledigt mit Kommentar ein.

Reklamationserfassung ?

Danach schreibt er einen Eintrag für das Anwenderprotokoll (also was der Anwender bei neuen Versionen erhält)

Das sind Informationen die direkt für den Kunden/User gedacht sind ?

Dazu bietet sich ein entsprechendes Changelog-File direkt in der Codebase an

(daraus kann man ja andere Dokumente automatisch generieren).

und einen Eintrag für das Developerprotokoll (für den Tester).

Informationen die für den Tester sind, würde ich grundsätzlich im Ticket

erfassen, bevor es an den Tester weitergegeben wird. Dieser sollte dann

auch bei Bedarf entsprechend die Testpläne anfassen.

Die Changes im VCS sollten jeweils in sich konsistent sein (also genau eben

***NICHT*** einmal pro Tag oder vor der Pause committen !) und den Zweck

der Änderung kurz und knapp beschreiben.

Dazu macht er noch einen Eintrag in der Zeiterfassung, was er gemacht hat.

Gehört ins Ticket.

Außerdem gibt der Entwickler nochmal mündlich Rückmeldung und gegebenenfalls muss er auch dem Kunden nochmal Bescheid geben.

Für sowas gibts doch Ticketsysteme.

Darüber hinaus muss natürlich der Quellcode kommentiert werden.

Ja, aber bitte Doxygen-Kompatibel und nur die wichtigen Dinge,

die nicht ohnehin selbsterklärend sind.

Ahja, und die Änderungen kommentiert man nicht im Sourcecode,

sondern im VCS.

Es sind also für jede(!) noch so banale Änderung am Programm an 3 bis 5 Stellen

Kommentare zu hinterlassen. Ich finde das unheimlich umständlich, zeitaufreibend

Und vorallem enorm teuer !

Benutzt ihr JIRA, OTRS, Polarion oder dergleichen?

hmm, da gäbs auch noch Redmine, Trac, Bugzilla.

Führt ihr die Ticket-Nr. im Quellcode mit?

In der commit-Message im VCS, damit man das dann automatisch

verknüpfen kann. Aber *NICHT* im Sourcecode.

Werden die Protokolle für ein Release automatisch durch das Ticketsystem

oder Bug-Tracking-System generiert?

Unterschiedlich. Hängt stark von der Projektgröße und der Release-Dichte ab.

Gibt es eine Integration mit der Versionsverwaltung?

Jain. Ich habe bisher noch keine Toolumgebung gesehen, die alle

benötigten Workflows direkt abbilden konnte. Ergo muß man sich

da vieles Projektspezifisch selbst zusammenstellen/-bauen.

[Pixie]

Die Changes im VCS sollten jeweils in sich konsistent sein (also genau eben

***NICHT*** einmal pro Tag oder vor der Pause committen !) und den Zweck

der Änderung kurz und knapp beschreiben.

Mal blöd gefragt: Wärs dann nicht besser, ein "nur mal zwischendurch Commit" entsprechend zu taggen? Die entsprechenden Commits könnte man dann bei weiterer Bearbeitung ignorieren?

Die Vorgehensweise mit den Ticketnummern im VCS und daran verknüpft die Änderungen im Sourcecode zu finden, wäre noch ausbaufähig... es gibt für VS eine SVN-Anbindung. Man könnte direkt für verschiedene Commits oder eine Gruppe von Commits (z.B. alle mit Ticketnummer xy oder mit Projekt abc verknüpften) Farben definieren, so dass auch im Sourcecode direkt zusammengehörige Änderungen farblich hintelegt sind. Das würde auch einen Überblick über mehrere commits hinweg erleichtern.

[gimbo]

Gut, damit kommen wir der Sache näher. Wir nennen unser eigenes Bug-Tracking-System eben Reklamationserfassung. Im Prinzip ist das aber nur eine elektronische Liste mit Fehlern und Wünschen, in der man als Support-Mitarbeiter oder Entwickler Kommentare hinterlassen kann und bei den einzelnen Vorgängen am Ende einen Haken mit "erledigt" setzt.

Das ist also recht rudimentär und daher sagte ich, dass meist auch noch eine mündliche Weitergabe des Bearbeitungsstatus' erfolgt. Ich kann als Entwickler eben nicht vernünftig mitteilen, ob eine Änderung nun getestet werden kann oder ob ich den Fehler reklamiere (z.B. weil ich ihn nicht nachvollziehen kann). Der Lebenszyklus eines Änderungswunsches lässt sich mit einem einzelnen Haken "erledigt" einfach nicht abbilden.

Wir haben keine Versionsverwaltung. Ich nutze zwar für mich selbst SVN auf meinem Rechner, aber das ist kein unternehmensweiter Standard. Demzufolge kann ich die Kommentarfunktion bei den Commits auch nicht wirklich nutzen, das wäre nur wieder eine zusätzliche Kommentarmöglichkeit. Das Fass Versionsverwaltung will ich lieber nicht angehen, das ist wieder ein eigenes Thema. Allein die Einführung eines Bug-Tracking-Systems wäre schon eine Herausforderung für sich. Weniger wegen der zu ändernden organisatorischen Abläufe als viel mehr wegen der fehlenden Unterstützung in der Geschäftsleitung.

[Pixie]

als viel mehr wegen der fehlenden Unterstützung in der Geschäftsleitung.

Dann werden wohl auich logische und/oder finanzielle Argumente nicht helfen?

[gimbo]

Nicht fakturierbare Aufträge werden halt nicht so gern gesehen.

Für die Anpassungen an der bestehenden "Reklamationserfassung" wurde 1 Tag eingeräumt. Ich halte das für Quatsch, weil man mit einem Tag vielleicht ein paar Kleinigkeiten verbessern kann, aber keine nennenswerte Effizienzsteigerung erreicht. Aus meiner Sicht müssten wir die Software in die Tonne hauen und uns ein System wie JIRA näher anschauen. Warum soll man das nachprogrammieren, was andere schon gut gelöst haben? Ein Tag wäre allein für die Evaluation der geeigneten Tools schon sehr knapp.

[Pixie]

Nicht fakturierbare Aufträge werden halt nicht so gern gesehen.

Die IT und Entwicklung ist bei Euch nicht Hauptabteilung, sondern eher eher Mittel zum Zweck? Wie groß seid Ihr denn (sprich, wie hierarchisch und bürokratisch läuft alles bei Euch ab)? Ihr habt keine QM?

Man könnte zur Optimierung der Arbeitsprozesse, der Qualitäts- und Effizienzsteigerung, und damit auch Kostensenkung, eine generelle Umstrukturierung vornehmen, die ein Arbeiten ermöglicht, wie es den aktuellen Standards entspricht.

[gimbo]

ca. 10 Personen (inkl. Auszubildende). Wir sind eine Softwarefirma. QM gibt es nicht. Das Thema ist zwar seit einiger Zeit immer wieder im Gespräch seitens der Geschäftsleitung, aber ich sehe bei dieser ablehnenden Haltung gegenüber echten Fortschritten eher schwarz. Leider wird seit ich hier bin (6 Jahre) so gut wie nichts in die eigenen Prozesse investiert und ich habe den Verdacht, dass dieser Zustand noch deutlich weiter zurückgeht. Es ist halt grotesk, dass wir von den eigenen Kunden erwarten, dass sie ihre Geschäftsprozesse an unsere Software anpassen, wir aber bei der Modernisierung unserer eigenen Prozesse eine erstaunliche Hüftsteifigkeit zeigen. Veränderung heißt bei uns, dass wir darüber nachdenken ob wir nicht noch irgendwo eine zusätzliche Excel-Liste einführen können oder ob wir irgendwo ein Datenfeld mit einem Standardwert vorbelegen können. So kommt es natürlich mit der Zeit zu einem "Reformationsstau".

Nun ja, ich denke ich bin an dieser Stelle ausreichend auf meine Beweggründe eingegangen.

[H0ff1]

Also für Ticketerstellung/ -bearbeitung benutzen wir unsere eigens entwickelte Software.

Haben wir ein Ticket abgeschlossen, setzen wir es auf den Status 'gelöst' und schreiben - bei Bugs - kurz rein, was den Fehler verursacht hat.

Und ansonsten noch bestimmte Hinweise für die QA zum testen, falls nötig.

Die Ticketnr. mit Titel des Tickets schreiben wir dann immer eine Changelog-Datei im Projekt und beim committen ins SVN das gleiche nochmal als Kommentar. So sieht man schneller, was im commit drin war.

Kommentare im Quellcode sind bei uns nicht unbedingt Pflicht. Wenn eben Code kommt der irgendwie besonders ist, oder kompliziert zu verstehen ist, sollte der halt kommentiert sein, damit der nächste auch weiß was da passiert, ohne ewig zu schauen.

Läuft so eigentlich einwandfrei kann mich nicht beklagen

[Thelvan]

jira mit svn anbindung

[biu]

Wir sind eine kleine Firma (1-10 Leute) und benutzen zur Zeit keinen Bugtracker. Wir haben mal eine weile das Ticketsystem vom Team-Foundation-Server genutzt allerdings ist das wieder im Sande verlaufen. Zur Dokumentation benutzen wir nur Kommentare zum Einchecken. Hat sich erstaunlich gut bewährt bisher ..

[metux]

@gimbo

wir haben ein selbstgestricktes Script, das git-commit der Form: Bugfix: 4711 Text

erkennt und damit den Bug 4711 auf erledigt setzt und "Text" als Erledigungskommentar im Bugzilla einträgt

Via commit-hook ?

Ein wenig tricky daran ist, daß man vorraussetzt, ein commit gleich den bug komplett fixt.

Bei kleineren Bugs ist das sicher voll ausreichend, aber bei komplexeren Problemen

(insbesondere wenn wir nicht nur bugs im engeren Sinne, sondern auch feature-requests

udgl. mit einbeziehen) könnte das schnell für ein wenig Durcheinander sorgen.

[metux]

Mal blöd gefragt: Wärs dann nicht besser, ein "nur mal zwischendurch Commit" entsprechend zu taggen? Die entsprechenden Commits könnte man dann bei weiterer Bearbeitung ignorieren?

Nein, diese zwischendurch-Commit gehören dann in eine temporäre Branch, die später

nochmal mit interaktivem Rebase wieder aufgeräumt wird (dh. also evtl. commits

zu logisch konsistenten Einheiten zusammenfassen und ggf. unnötige Änderungen

wieder wegräumen).

Wichtig zu verstehen ist, daß ein VCS nicht einfach nur eine Bearbeitungshistorie

ist, sondern auch eine längerfristige Dokumentation des Entwicklungsverlaufs

(dh. man kann später jederzeit nachschauen was warum geändert wurde).

Insofern ist es auch wichtig, die History möglichst linear zu halten, damit zB.

Operationen wie bisect gut durchlaufen können.

[metux]

Wir sind eine kleine Firma (1-10 Leute) und benutzen zur Zeit keinen Bugtracker. Wir haben mal eine weile das Ticketsystem vom Team-Foundation-Server genutzt allerdings ist das wieder im Sande verlaufen. Zur Dokumentation benutzen wir nur Kommentare zum Einchecken. Hat sich erstaunlich gut bewährt bisher ..

Nunja, TFS für Sourcecode zu verwenden halte ich für keine sonderlich gute Idee.

[metux]

Das ist also recht rudimentär und daher sagte ich, dass meist auch noch eine mündliche Weitergabe des Bearbeitungsstatus' erfolgt. Ich kann als Entwickler eben nicht vernünftig mitteilen, ob eine Änderung nun getestet werden kann oder ob ich den Fehler reklamiere (z.B. weil ich ihn nicht nachvollziehen kann). Der Lebenszyklus eines Änderungswunsches lässt sich mit einem einzelnen Haken "erledigt" einfach nicht abbilden.

Da wäre es durchaus hilfreich, mal andere Tracker-Systeme, zB. Bugzilla, Redmine, Trac, usw, zu evaluieren.

Diese haben idR. einen gewissen Ticket-Workflow, mit dem man die Bearbeitungszustände abbilden kann.

Bei Redmine ist das aktuell noch sehr rudimentär, aber das werd ich mir vorraussichtlich im Q2 mal

eingehend vornehmen (evtl. sogar eine generische Workflow-Engine dafür andocken, mit der auch

komplexe WF's abbilden kann).

Bearbeitet 16. Januar 2012 von metux

[metux]

Mal blöd gefragt: Wärs dann nicht besser, ein "nur mal zwischendurch Commit" entsprechend zu taggen? Die entsprechenden Commits könnte man dann bei weiterer Bearbeitung ignorieren?

Was genau nutzt das, wenn am Ende dann die History (der Mainline) dennoch mit solchen inkonsitenten/kaputten Versionsständen vermüllt ist ?

Bei temporären Branches kann man das gerne machen, wenn man hinterher ohnehin alles nochmal mittels interaktivem rebase wieder aufräumt,

aber permantentere branches (mainline, maintenance branches, etc) sollten stets nur in sich konsistente commits enthalten.

[Pixie]

Was genau nutzt das, wenn am Ende dann die History (der Mainline) dennoch mit solchen inkonsitenten/kaputten Versionsständen vermüllt ist ?

Bei temporären Branches kann man das gerne machen, wenn man hinterher ohnehin alles nochmal mittels interaktivem rebase wieder aufräumt,

aber permantentere branches (mainline, maintenance branches, etc) sollten stets nur in sich konsistente commits enthalten.

Das Ignorieren war jetzt für die Verwendung außerhalb z.B. für eine Versionshistorie für den Kunden o.ä. gedacht.

Ich kenne das Arbeiten mit CVSs aber bisher auch nur sehr eingeschränkt... und zwar mit dem Hauptziel, den Code zentral zu sichern und ihn allen Projektbeteiligten zugänglich zu machen, inklusive der Verfolgbarkeit, wer wann welche Änderungen vorgenommen hat. Dabei ist das Kommentierverhalten sehr... ähm.... individuell unterschiedlich ausgeprägt, um es mal nett zu sagen. Wenn unser Chef in einem Projekt einen Commit ausführt, bei dem das SVN einen kommentar erwartet, steht da meist nur eine vierstellige Buchstabenkombination ohne Bedeutung, weil das das Mindestkriterium für den Commit ist. im gleichen Umfang werden auch bei uns Dokumentationen durchgeführt: gar nicht. Das Geschrei ist zwar meist hinterher groß, aber Handlungsbedarf etwas zu ändern, sieht irgendwie keiner und meine Meinung als Exazubi ist zwar "interessant" aber mehr auch nicht.

[H0ff1]

Ich kenne das Arbeiten mit CVSs aber bisher auch nur sehr eingeschränkt... und zwar mit dem Hauptziel, den Code zentral zu sichern und ihn allen Projektbeteiligten zugänglich zu machen, inklusive der Verfolgbarkeit, wer wann welche Änderungen vorgenommen hat. Dabei ist das Kommentierverhalten sehr... ähm.... individuell unterschiedlich ausgeprägt, um es mal nett zu sagen. Wenn unser Chef in einem Projekt einen Commit ausführt, bei dem das SVN einen kommentar erwartet, steht da meist nur eine vierstellige Buchstabenkombination ohne Bedeutung, weil das das Mindestkriterium für den Commit ist. im gleichen Umfang werden auch bei uns Dokumentationen durchgeführt: gar nicht. Das Geschrei ist zwar meist hinterher groß, aber Handlungsbedarf etwas zu ändern, sieht irgendwie keiner und meine Meinung als Exazubi ist zwar "interessant" aber mehr auch nicht.

Also für das Kommentieren eines Commits haben wir eine Regel, die ich auch sehr gut finde, da kennt man sich dann wenigstens noch aus :

Die Commit-Message soll immer die Ticketnummer und den Titel des Tickets enthalten also z.B. so: "- (12345) Titel des Tickets". Wird später ein Fix zu diesem Ticket committet, soll man ein "[FIX]" dahinter schreiben (Gibt es mehrere, wird's durchnummeriert). Ist nur ein Teil des Tickets gelöst schreibt man ein "[PARTIAL]" dahinter.

Ein commit muss bei uns also immer ein Ticket haben. Gibt's zu irgendwas noch kein Ticket, soll man dazu eins anlegen, reinschreiben, was das Problem ist und wenn es nach den Commit behoben ist, lösen.

So finde ich hat man eine gute History bei der man immer weiß wer, wann, was und warum gemacht hat.

Die Commit-Message ist dann auch nicht zu lang. Man weiß anhand des Tickettitel, worum es da ungefähr geht und wenn man genaueres dazu wissen will kann man das im entsprechenden Ticket nachlesen.

Also ich find das gut so und es funktioniert

[metux]

Das Ignorieren war jetzt für die Verwendung außerhalb z.B. für eine Versionshistorie für den Kunden o.ä. gedacht.

Also eine kundenseitige Dokumentation hat doch einen völlig anderen Scope. Daraus ergibt sich

zB. eine viel gröbere Granularität, andere Strukturierung und Formulierungen. Sowas sollte man

wohl besser manuell pflegen.

Ich kenne das Arbeiten mit CVSs aber bisher auch nur sehr eingeschränkt...

Mit CVS kann man auch nur sehr, sehr eingeschränkt arbeiten.

(sehr diplomatisch ausgedrückt!)

Wenn unser Chef in einem Projekt einen Commit ausführt, bei dem das SVN einen kommentar erwartet, steht da meist nur eine vierstellige B auch uchstabenkombination ohne Bedeutung, weil das das Mindestkriterium für den Commit ist. im gleichen Umfang werden auch bei uns Dokumentationen durchgeführt: gar nicht. Das Geschrei ist zwar meist hinterher groß, aber Handlungsbedarf etwas zu ändern, sieht irgendwie keiner und meine Meinung als Exazubi ist zwar "interessant" aber mehr auch nicht.

Vielleicht sollte man da mal einen externen Berater einkaufen - richtig teuer, dann gibts auch mehr Anerkennung ;-o