Wie dokumentiert ihr Einmannprojekte?

  • Allgemein

Es gibt 47 Antworten in diesem Thema. Der letzte Beitrag () ist von ~blaze~.

    @ErfinderDesRades

    jvbsl schrieb:

    Und ich glaube @RodFromGermany meinte mit seinem Satz eben XML kommentare.
    Ja, es ist so. Der Haken im Projekt gehört zu den firmen-gegebenen Projekteinstellungen.
    Kommentare zwischendurch da, wo sie nötig sind.
    Wenn ich ein Projekt übernehme (und die beiden letzten dieser waren praktisch unkommentiert) fräse ich erst mal quer durch und formatiere den Code nach den neuen Vorschriften (@EDR: Da würdest Du Dich wohl im Grabe herum drehen, { und } stehen da einzeln in einer Zeile). Die Forderung ist, dass das Codelayout aller Entwickler praktisch identisch aussehen soll.
    Da werden grob Strukturen identifiziert, GUI, Hardware usw. initialisieren, Settings verwalten usw. und als solche kommentiert, meist nur ein Wort.
    Da die XML-Kommentare bei HOver angezeigt werden, pflege ich die sehr, auch für private Prozeduren. Mit der Zeit kommt dann die Erkenntnis, was der Code wirklich tut, da werden die Kommentare präzisiert.
    Mein Chef hat inzwischen eingesehen, dass die Kommentierung des Codes essenziell wichtig ist, weil hier eben zwei meiner Vorgänger ein Chaos hinterlassen haben.
    Im Kommentar zum CheckIn der Sourcecodeverwaltung steht da eben manchmal einfach nur "Code aufgeräumt und kommentiert".
    Aber die History.txt im Projekt wird ordentlich gepflegt, um dann schneller die Version vor einer Änderung zu finden.
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!

    ~blaze~ schrieb:


    Ich würde jetzt aber ehrlich gesagt die philosophische Diskussion nur ungern weiter ausufern lassen, auch wenn sie sicher interessant sein mag (gerne aber privat, sofern es auch irgendwann ein Ende findet). Es sind noch immer konkrete Fragen zu beantworten:


    Manche sind da wohl nicht zu bremsen.

    Um wieder zum Thema zurück zu kommen, eine kurze Zusammenfassung über das, was ich bis jetzt mitbekommen habe:
    • XML-Kommentarfunktion benutzen -> daraus lässt sich eine Dokumentation mit einem Sandcastle-Nachfolger generieren
    • so viele Kommentare wie nötig, wobei man immer die Sinnhaftigkeit eines Kommentars hinterfragen sollte
    • VS kann UML-Diagramme generieren, allerdings fehlt die Funktion leider in VS Express
    • Klassendiagramme werden allgemein als Sinnvoll angesehen
    • auf Namenskonventionen achten
    • mit Git kann man den Projektverlauf dokumentieren, aber es erfordert etwas Einarbeitungszeit
    Option strict = on

    If it's stupid and it works it ain't stupid.

    Nils_Kr schrieb:

    mit Git kann man den Projektverlauf dokumentieren, aber es erfordert etwas Einarbeitungszeit
    Mit jedem Sourcecode-Verwaltungs-Tool.
    Meins wäre SVN.
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!

    Nils_Kr schrieb:

    Um wieder zum Thema zurück zu kommen, eine kurze Zusammenfassung über das, was ich bis jetzt mitbekommen habe:
    1. XML-Kommentarfunktion benutzen -> daraus lässt sich eine Dokumentation mit einem Sandcastle-Nachfolger generieren
    2. so viele Kommentare wie nötig, wobei man immer die Sinnhaftigkeit eines Kommentars hinterfragen sollte
    3. VS kann UML-Diagramme generieren, allerdings fehlt die Funktion leider in VS Express
    4. Klassendiagramme werden allgemein als Sinnvoll angesehen
    5. auf Namenskonventionen achten
    6. mit Git kann man den Projektverlauf dokumentieren, aber es erfordert etwas Einarbeitungszeit
    Ich sag immer: Kopf anmachen und überlegen, was nötig ist. Und das dann machen.
    Nicht mehr machen, und auch nicht vorauseilend was machen.
    Sondern das nötige machen, wenns nötig ist.
    (Und selbstverständlich es auch nicht unterlassen)

    Zu 4. Das ist nicht richtig - ich zumindest sehe Klassendiagramme nicht allgemein als sinnvoll an.
    Aber schadet auch nicht - ist ja generiertes Zeugs, und läuft daher nicht Gefahr, durch vergessene Pflege bei der Code-Weiterentwicklung in einen "Lügenden Zustand" zu kommen.

    Zu 3. Brauchst du UML-Diagramme?
    Definiere UML-Diagramm erstmal. AFAIK sind Klassendiagramme ja auch UML.
    Wie dem auch sei - ich hab noch nie ein UML-Diagramm gesehen, anhand dessen mir etwas klarer geworden wäre, als wenn ich bischen im Code gebuddelt hätte.
    Entweder waren die Diagramme so abstrakt, dasses eiglich nicht mehr war als hübsch aufgemaltes "BlaBla".
    Oder es ging ins Detail, dann wurden die Dinger aber quadratkilometer groß, und damit unübersichtlicher als der Code, den sie beschreiben wollten.
    Und händisches UML hat wieder den "Lüge-Faktor" - also wenn das nicht ständig höchst aufwändig gepflegt wird, ists nicht nur nutzlos, sondern regelrecht schädlich.

    zu 1. Ich hoffe, dir ist bekannt, dass Xml-Kommentare mit sofortiger Wirkung Bestandteil der Doku des ObjectBrowsers werden.
    Für welche Zwecke brauchst du noch eine weitere, Sandcastle-generierte Doku?

    Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „ErfinderDesRades“ ()

    @ErfinderDesRades
    Das ärgert mich jetzt schon ein wenig. Weise doch bitte wenigstens darauf hin, dass hier auch andere Meinungen vorherrschen, als deine eigene. Jetzt übergehst du einfach alle anderen Hinweise und erzählst nur deine eigene Meinung. Selbst obwohl man dir bereits aufgezeigt hat, dass du gewisse Probleme noch nie hattest.
    Da wäre eine Zusammenfassung wesentlich hilfreicher gewesen.

    @Nils_Kr
    Lies dir nochmal die anfänglichen Beiträge durch. Zumindest jene bis einschließlich 6. Anschließend überlege, welche du als sinnvoll erachtest und welche nicht und baue auf diesem Fundament dein eigenes Prinzip auf.

    Meine Meinung zu deinen Punkten
    1.: Nutze die XML-Kommentarfunktion für öffentliche Member und dokumentiere alles. Sandcastle habe ich nicht verwendet, da ich bisher keine .Net-Dokumentation exportieren musste. Ansonsten habe ich sie manuell erstellt oder würde sie automatisiert generieren lassen
    2.: So viele Kommentare wie nötig, um zu verstehen, wieso du gemacht hast, was du gemacht hast und ggf. auch, warum du es nicht anders gelöst hast. Kommentare an eine sinnvolle Position, sodass Sinn und Zusammenhang erkennbar sind
    3.: UML-Diagramme nur, wenn sie sinnvoll sind und aufklärend. Wenn zu viel drauf ist, verliert sich die Übersichtlichkeit, wenn zu wenig drauf ist, erkennt man keinen Nutzen.
    4.: Klassendiagramme sind nicht sinnvoll, wenn sie keinen Sinn erfüllen. Eine Erklärung gehört dazu.
    5.: Konventionen definitiv einhalten, wann immer möglich. Einheitlichkeit erleichtert das Denken.
    6.: Die Einarbeitungszeit in Git ist es definitiv wert.

    Wenn du irgendwelche Bilder, usw. in deine Dokumentation wirfst, muss das einen Grund haben. Sie sollten intuitiv verständlich sein und schneller oder übersichtlicher erklären, als ein Text. Ein Text sollte außerdem die Grafik noch erläutern oder zumindest kurz darauf hinweisen, was die Grafik zeigt.
    Ich versuche außerdem stets einen klaren Rahmen zu ziehen: "Um was geht es?" und "um was geht es nicht?", sofern das nicht offensichtlich durch ersteres gegeben ist und man in die Irre geführt werden könnte.

    Viele Grüße
    ~blaze~
    Wenn ich mich nicht irre, sind die UML-Diagramme was für Chefs, die von Software keine Ahnung haben, aber ihren Chefs und den Gästen die Tollizität der Software erklären sollen. ;)
    Ich kannte mal einen Entwickler, der von dem damaligen Projekt der SW-Architekt war, der hat sich von einem UML-Generator Klassen generieren lassen.
    Das hat mich sehr gestört, weil da die Properties alphabetisch und nicht logisch sortiert waren.
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!

    ~blaze~ schrieb:

    Das ärgert mich jetzt schon ein wenig. Weise doch bitte wenigstens darauf hin, dass hier auch andere Meinungen vorherrschen, als deine eigene. Jetzt übergehst du einfach alle anderen Hinweise und erzählst nur deine eigene Meinung. Selbst obwohl man dir bereits aufgezeigt hat, dass du gewisse Probleme noch nie hattest.nullDa wäre eine Zusammenfassung wesentlich hilfreicher gewesen.
    Hää?
    Aber selbstredend erzähle ich nur meine Meinung - wie könnte man denn drauf kommen, ich erzählte etwas anderes?
    Füe eine zusammenfassung bin ich ühaupt nicth zuständig - es war @Nils_Kr, der die Zusammenfassung gemacht hat, über das, was er scheints hier mitnimmt.
    Zu 3 Punkten seiner Zusammenfassung habe ich meine - meine! - Anmerkungen gemacht, sonst nix - was gibts daran sich zu ärgern?

    Das darauf hinweisen, dass "hier auch andere Meinungen vorherrschen" kann ich garnet leisten, schon weil ich nicht weiß, welche im Einzelnen, und ob sie "vorherrscht" - ist ja je nach Thema verschieden.
    Also kann ich allenfalls drauf hinweisen, dasses auch andere Meinungen als meine gibt. Ja, schön - nur ist das super-trivial.
    Du kannst also nicht die von dir als sinnvoll erachteten Paradigmen als global gültig ansehen, da du nicht alles kennst, was sich hinter dem Horizont erstreckt, den du bisher nicht erblickt hast. Du kennst nur das, was du kennst und das geht jedem so. Ich habe schon Projekte in sehr vielen verschiedenen Bereichen durchgeführt oder zumindest kleine Prototypen für Problemstellungen aus diesen angefertigt. Daher wage ich auch die Abschätzung, welche Probleme von deinen aufgelisteten Prinzipien in den Situationen nicht zielführend sind. Es geht mir sehr darum, zu sagen, dass das nicht pauschal so festlegbar ist, weil es einfach total auf die Situation ankommt.

    ErfinderDesRades schrieb:

    Sondern das nötige machen, wenns nötig ist.

    Das kommt völlig darauf an. Wenn du erst einmal eine stabile Alphaversion programmieren willst, lohnt es sich, die Architekturarbeit schon vorab zu machen und zu schauen, wo man hin will und wie es sich rentiert, das zu gestalten.
    Hier kann UML zur Designentscheidung kritisch sein: Du hast den Überblick über die Komponenten, die es zu programmieren gilt und wie sie zusammenhängen. Du kannst darauf wunderbar entscheiden. Anhand der Diagramme lassen sich auch kritische Bereiche, wie bspw. Parallelität, wunderbar illustrieren. Man sollte - Vorsicht: Meine Meinung - bei solchen Projekten nicht beim Programmieren beginnen, sondern die Architektur vorab festsetzen.
    Sobald man mit Generika, Interfaces und abstrakten Klassen arbeitet, bläht sich die Architektur in eine derart hohe Komplexität auf, dass es schwer wird, den Überblick zu bewahren, sobald das Projekt mal eine gewisse Komplexitätsgrenze überschreitet.
    Und genau an diesem Punkt würde man es bereuen, wenn man dieses von dir postulierte Nötige falsch angelegt hat. Man hat jede Menge Redundanz im Code, weil man ständig mit auf einer gewissen Ebene analogen Problemen konfrontiert ist.
    Insofern halte ich die Aussage nicht für jeden Fall anwendbar und damit für falsch.

    ErfinderDesRades schrieb:

    Zu 4. Das ist nicht richtig - ich zumindest sehe Klassendiagramme nicht allgemein als sinnvoll an.
    Aber schadet auch nicht - ist ja generiertes Zeugs, und läuft daher nicht Gefahr, durch vergessene Pflege bei der Code-Weiterentwicklung in einen "Lügenden Zustand" zu kommen.

    Wichtig ist, dass man die Dokumentation up-to-date hält. Ich persönlich halte es so, dass die Dokumentation - falls nicht anders gefordert - jene Komponenten genau dokumentiert, die andere verwenden und der Rest nur für mich ist (d.h. Notizen. Höchstens mal einen groben Überblick für die anderen - ist natürlich auch immer davon abhängig, ob das geht/sinnvoll ist und sehr abhängig vom Team und wohl auch von der Firma bzw. der verwendeten Organisation). Bei Ein-Mann-Projekten, wie bei dir gefodert habe ich insofern eben eine Dokumentation, die erst mal nur mir dient, es zu verstehen und einen Überblick zu behalten. Die genaue Dokumentation wird dann zu jedem Release überarbeitet und kritisch von mir oder Anderen korrekturgelesen. Das hat in den bisherigen Projekten auch recht gut geklappt und wenn mal wirklich Fragen da waren, hab' ich mir halt die Zeit genommen, eine genaue Beschreibung zu erstellen oder ein Gespräch zu führen.

    ErfinderDesRades schrieb:

    Wie dem auch sei - ich hab noch nie ein UML-Diagramm gesehen, anhand dessen mir etwas klarer geworden wäre, als wenn ich bischen im Code gebuddelt hätte.

    Das wird ab einem gewissen Komplexitätsgrad einfach nicht mehr möglich sein. Wenn du Projekte mit mehreren hundert Klassen hast mit durchschnittlich 200 Zeilen und dutzenden verschiedenen Zwecken/Ideen/Konzepten, bist du mit dem Code-Buddeln komplett überfordert. In einem guten UML-Diagramm kann man diese Dinge illustrieren.

    Ich würde das von Vornherein nicht ablehnen. Die Sinnhaftigkeit der Diagramme muss aber, wie gesagt, auf jeden Fall immer gegeben sein.

    ErfinderDesRades schrieb:

    Oder es ging ins Detail, dann wurden die Dinger aber quadratkilometer groß, und damit unübersichtlicher als der Code, den sie beschreiben wollten.

    Das ist dann bspw. ein Fall, in dem ich dem Schöpfer sagen würde, dass er das nochmal überdenken soll. Die Sinnhaftigkeit erschließt sich mir dann nicht - sofern nicht der Text klar beleuchtet, was genau dahintersteckt.

    ErfinderDesRades schrieb:

    Für welche Zwecke brauchst du noch eine weitere, Sandcastle-generierte Doku?

    Das hatte ich vorhin erläutert. Und das ist z.B. auch was, was mich dann ärgert, sofern du es gelesen hast. Übersichtlichkeit, Webservice, Wartbarkeit, usw. In der MSDN z.B. findest du weitaus detailliertere Beschreibungen, als im Framework selbst. Oftmals auch Code.

    Irgendwie habe ich nicht mehr wirklich den Drang, der Diskussion weiter beizuwohnen. Ich habe so im Moment zu viel zu tun, als dass ich mir da nochmal gerne so viel Zeit nehmen würde.

    Viele Grüße
    ~blaze~