Wie dokumentiert ihr Einmannprojekte?

  • Allgemein

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

    Wie dokumentiert ihr Einmannprojekte?

    Hi,

    der Titel sagt ja schon das Meiste. Ich arbeite gerade als Werksstudent an einem Projekt, bei dem ich der einzige Programmierer bin (ca. 4000 Zeilen Code, also noch überschaubar). Die Anforderungen und Ziele sind recht klar gestellt.
    Nur bei der Dokumentation gibt es keinerlei Anforderungen. Ich würde aber gerne eine erstellen, hauptsächlich um dabei etwas zu lernen.

    Jetzt gehen die Meinungen im Internet & der Literatur allerdings sehr weit auseinander. Manche lehnen externe Dokumente komplett ab und befürworten einzig die Dokumentation per Kommentaren. Andere sehen UML-Diagramme, Modulübersichten etc.
    als elementar an.

    Mir geht es dabei weniger um eine Bedienungsanleitung, sondern um die Lesbarkeit des Codes.

    Wie handhabt ihr das so?

    *Topic verschoben*
    Option strict = on

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

    Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „Marcus Gräfe“ ()

    Schritt 1 : XML Kommentare. Mit Tools wie Sandcastle (inzwischen veraltet, suchen danach zeigen aber die "neuen" alternativen) können daraus ganze Dokumentationen erstellt werden.
    Schritt 2 : Klassendiagramme. VS macht das für dich.
    Schritt 3 : Was auch immer du als nützlich für andere Personen findest, um deinen Code zu verstehen. ("andere Personen" schließt dein zukünftiges ich ein, das nicht mehr die Übersicht über den Code hat.)
    Hi
    je nach Projektart halte ich es idR. so, dass ich erst grundlegende Konzepte beschreibe und den groben Aufbau beschreibe und ausgewählte elementare Bestandteile herauspicke, die ich dann weiter ausführe. Dieser Teil ist also eher für den Anwender interessant. Anschließend kommt häufig eine detailliertere Beschreibung aller Komponenten, was sowohl Anwender, als auch Programierer interessieren dürfte. Danach kommen noch nicht selbsterklärende Dinge, wie bestimmte Methoden. Am Schluss habe ich bisher meist noch eine Auflistung aller nicht allgemein geläufigen Algorithmen oder Grundsätze in einer Art Appendix zusammengefasst, sofern nicht eine Quelle besser geeignet war (wobei auch das teilweise unerwünscht ist).

    Teilweise ist es dann auch sinnvoll, eine Referenz zu exportieren, die nochmal einen Überblick über alle Objekte und Methoden bietet.
    Klassendiagramme eignen sich auch gut, um die Zusammenhänge klarzumachen. Ich persönlich halte Ablaufdiagramme eher nicht für so sinnvoll, da sie die Dinge meist nicht besser darstellen, als gut strukturierter Code an sich. An sich hält man allerdings durch die Verwendung die Dinge beieinander, d.h. man hat alles im Dokument und muss nicht erst zum Code gehen (was allerdings bei Wartungsarbeiten auch ein Nachteil sein kann. Ich würde also im Code auch die Dinge schreiben, die ich im Ablaufdiagramm geschrieben habe).

    Allgemein hat man die Zeit nicht, das so zu machen (es handelte sich oben um Projekte mit sehr großem Zeitfenster), d.h. meist beschränkt man sich dann darauf, die Sachen halbwegs verständlich zu erklären. Einige Firmen verzichten von vornherein auf eine Dokumentation des Codes oder lassen sie direkt automatisiert erzeugen. Das kann allerdings niemals so gut werden, wie wenn jemand es manuell ausführt.

    Solange nicht anders erbeten, gilt bei mir der Grundsatz, dass alle Dinge verständlich erklärt sein müssen, d.h. man kann sich an UML bedienen, wenn dies zur Visualisierung gut geeignet ist. Ansonsten immer darauf achten, dass es möglichst schnell verständlich ist, wobei bei mir hier der Grundsatz gilt: Schnell klar machen, was gemeint ist, schnell klar machen, was nicht gemeint ist.

    Übrigens macht es teilweise auch noch Sinn, Konventionen oder bestimmte Paradigmen aufzuführen, nach denen man den Code ausgearbeitet hat. D.h. worauf hat man Augenmerk gelegt, welche "Besonderheiten" finden sich im Code wieder, usw.
    Wichtig ist außerdem, dass die Codedokumentation möglichst präzise ist: Welche Exceptions werden geworfen (auch die, die vom ausgeführten Code ausgeführt werden!), Threadsicherheit, usw.

    Was ich teilweise auch für mich mache, ist eine Schnellübersicht, um wieder schnell in den Code einzusteigen.

    Viele Grüße
    ~blaze~
    Servus,

    im Projekt unserer Firma nutzen wir gleich mehrere Möglichkeiten, alles zu dokumentieren - macht Sinn wenn ein Projekt wie in unserem Fall knapp 2 Millionen (1.8M) Code-Zeilen hat. Ist eine Webapplikation nebenbei bemerkt. Und nicht nur die Dokumentation ist in dem Fall wichtig sondern auch das "Drumherum".

    Konsequente Namenskonventionen und Code Style
    Für die Übersichtlichkeit ist es wichtig, dass auch der Rest stimmt und man sich an der Namensgebung von Methoden, Eigenschaften, Konstanten und Variablen schnell orientieren kann. Der Code an sich ist ist logisch in Namespaces gegliedert, Klassen leiten sich von abstrakten Klassen und Interfaces ab, sodass der nächste der eine Funktionalität erweitert sich trotzdem an fest definierte Standards halten muss.
    Außerdem sind die IDEs so eingestellt dass das Formatting für die verschiedenen Dateitypen einheitlich ist.

    Code-Kommentare
    Kommentare im Code sind unerlässlich, ohne geht gar nicht. Jede Klasse, Methode und die meisten Eigenschaften und Konstanten sind kommentiert. Dazwischen auch noch mit Single-Line-Comments um einen Vorgang zu beschreiben. Typehints, return und Exceptions macht die IDE sowieso automatisch.

    Modulare Beschreibungen (Library descriptions)
    Bei gesammelten Klassenmodulen wird zusätzlich im entsprechenden Verzeichnis eine readme.md abgelegt, die grob beschreibt, was ein Modul oder eine Lib tut und wie sie zu benutzen / einzubinden ist. Dazu noch schnell eine Verlinkung zu den wichtigsten Files (Config-Dateien oder nutzbare Klassen). Das ist für Kollegen eine gute Übersicht ohne dass sie in den Code schauen müssen.

    Versionierung
    Bei jedem Commit muss eine aussagekräftige Commit-Message angegeben werden (was wurde verändert, was ist neu, jegliche Änderung die bestehenden Code beeinflussen) und eine Beschreibung insgesamt (z.B. "betrifft Änderungen für Kunde XY im Plugin-Modul"). In der Commitmessage werden ggf. verknüpfte IDs zum Ticketsystem oder Revisions zu zusammenhängenden Commits verlinkt.

    Wiki
    In unserem Fall gibt's noch ein (internes) Wiki, in dem die größten, hauptsächlichen Änderungen zusammengefasst sind. Außerdem werden dort Schritte zu bestimmten Aktionen und Prozessen beschrieben.

    Manual
    Das User-Manual für den End-Anwender, wo drin steht wie er diesen und jenen Shit erledigen kann (z.B. "wie lege ich Kunden an" und solcher Krempel).

    Wie weit man da geht, bleibt jedem selbst überlassen, aber je größer das Projekt desto wichtiger ist es, dass alles gut strukturiert ist. Und dann kann man's ja gleich von Anfang an richtig machen.
    Es gibt ja Leute die sagen dass für eine Doku "keine Zeit" ist - das ist Schwachsinn (// EDIT @~blaze~ nicht falsch verstehen, das hab ich geschrieben noch bevor ich deinen Beitrag gelesen hab). Die Zeit die jemand anderes braucht um ohne Doku oder Kommentare in das Projekt einzusteigen kostet viel mehr als wenn sich der Programmierer die paar Minuten Zeit nimmt und alles ordentlich beschreibt.

    Zur eigentlichen Frage
    Wenn ich alleine an einem Projekt sitze, handhabe ich das alles im Grunde genauso (nur ohne das Wiki). Ich mag's einfach wenn der Code gut strukturiert ist und ich in einem halben Jahr immer noch auf einen Blick nachvollziehen kann was wo passiert.


    Link :thumbup:
    Hello World

    Dieser Beitrag wurde bereits 4 mal editiert, zuletzt von „Link“ ()

    @All Jou.
    Obwohl schon überall gesagt: Prozeduren, Properties usw. kommentieren ist ein Muss (/// bzw. ''' über dem zu kommentierenden Code). Dies wird einem selbst bei der Entwicklung angezeigt.
    Mein Chef gab mir ein älteres Projekt, das ich weiterführen soll, das war im Prinzip gar nicht dokumentiert, mein Vorgänger hatte es nicht nötig und war dann mal weg. X(
    Das wichtigste am Dokumentieren des eigenen Codes ist, dass man in einem halben Jahr oder so, wo in der Zwischenzeit am Code nix passiert ist, sich schnell wieder reinfinden muss, um die anstehenden Änderungen einzuarbeiten.
    Ich hab in meinen Projekten eine History.txt drin, wo ich mit Datum die Änderungen grob aufliste. Das macht sich gut bei der Suche, wann eine Änderung eingepflegt wurde, um fix den vorherigen Stand 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!
    ich sehe die Doku-Kommentare nicht als ein Muss.
    Zu dokumentieren ist Code, der nicht selbsterklärend ist.
    Eine Sub New mit der Erklärung auszustatten, dass das der Konstruktor ist, der ein Objekt dieser Klasse baut - solch ich Hirn-Sch....
    Einen parameter namens filePath zu erläutern, dass das ein Dateipfad ist - ebenso.
    Also Hirn anmachen beim Dokumentieren, und dokumentieren, was es nötig hat - und alles andere ganz bewusst nicht.

    Ich persönlich erstelle gerne ausschweifende File-Header.
    Weil Kommentare innerhalb der Dateien stören, und verschlechtern den Überblick.
    Aber ein FileHeader kann Grundgedanken behandeln, Zusammenhänge mit anderen Dateien aufzeigen, Aufrufe-Beispiele, unerledigtes Optimierungspotential...
    Das stört ühaupt nicht, weil es kommt eine Region drumrum, und kannste zuklappen.
    Das kann ich für mich nicht bestätigen - was nicht heißt, dass es nicht auch eine Möglichkeit ist. Ich finde es allein aus Gründen der Vollständigkeit wichtig, auch solche Dinge zu kommentieren.
    Bspw. würde ich tatsächlich bei filePath schreiben, dass es sich um z.B. den Pfad handelt, aus dem gelesen werden soll.
    Die Konsequenz ist für den Leser übrigens auch, dass er das Gefühl hat, dass die Anwendung Hand und Fuß hat.

    Bzgl. der File-Header: Ich schreibe da dann eher "see reference file, chapter IV" oder sowas. Code wird in Sinnabschnitte gegliedert (durch Paragraphen) und oberhalb von diesem sind jeweils Kommentare, die mit einer Leerzeile den neuen Paragraphen einleuten:

    C#-Quellcode

    1. //Foo, by doing some weird stuff
    2. Bla()
    3. //Check for foobar
    4. if (is1234Integer())
    5. ...
    6. //new paragraph
    7. Bla2()


    wobei das nur auf komplexe Methoden zutrifft. Meist reduziere ich das dann halt entsprechend. Somit bleibt es - in meinen Augen - übersichtlich und intuitiv strukturiert.

    Viele Grüße
    ~blaze~
    @blaze:
    nee - Leerzeilen sind mir auch nix.
    Ich will Code sehen, wenn ich Code angucke - keine Schwafel-Kommentare, und keine Leerzeilen.
    Gute Übersicht ist, wenn ich 3 Methoden auf einem Bildschirm hab - wenn das durch Kommentation und Leerzeilen auf 2 Bildschirme sich verteilt, und ich muss scrollen - nicht so gut.
    @ErfinderDesRades Das ist Geschmackssache.
    Und da gibt es noch firmeninterne Codierungsregeln, und ich seh nicht ein, dass ich mir bei meinen privaten Projekten da einen anderen Stil aneignen soll.
    Sehen sie halt genau so aus. :D
    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!

    RodFromGermany schrieb:

    Geschmackssache?
    Bin ich von unüberzeugt.
    Imo ist das sachlich begründet (und damit keine Geschmacksache) wenn ich übersichtlicher nenne, wenn derselbe Code auf 1 Bildschirm zu sehen ist, ohne Scrollen und ohne Geschwafel dazwischen.
    Aber wer's unbedingt als "Geschmacksache" abtun will - kann man natürlich nix beweisen - müsste man ja jahrelange wissenschaftliche Untersuchungen fahren, um auch nur statistische Tendenz-Aussagen machen zu können.

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

    Die Sache ist das in der Firma der Code auch in 10 Jahren von einen Kollegen verstanden werden muss der dich vielleicht nicht mehr fragen kann. Da ist es egal ob er scrollen muss oder nicht. Jedoch geht es hier ja um Projekte die vermutlich keiner anfasst außer derjenige selber von daher ist es wirklich Geschmacksache.
    ich rede von Schwafel-Kommentaren.
    Und auch in 10 Jahren wird man wissen, was ein Konstruktor ist und was ein filePath - auch ohne mich zu fragen.

    Ich rede garnet generell gegen Kommentation.
    Grad wenn ich Geschwafel weglasse treten die Kommentations-Notwendigkeiten umso deutlicher hervor.

    Und für in 10 Jahren empfehle ich noch einmel File-Header, wo die Konzepte erläutert sind, die der Code umsetzt.
    Das ist jdfs. oft bei mir das Problem, dass ich an Klassen gerate, wo ich Stunden brauche um zu schnallen, was die ühaupt sollen.
    @ErfinderDesRades: Kommentare im Code sind immer sinnvoll, wenn es etwas kompliziertere Algorithmen sind, oder die Algorithmen eben optimiert wurden, dass diese schwerer zu verstehen sind. Aber wenn man natürlich immer nur einfache Programme schreibt kann man die Kommentare ruhig weg lassen.
    Und dass gerade du als oberster Verfechter der MSDN gegen die XML Kommentare bist wundert mich doch jetzt doch etwas, da man doch eben daraus eine wunderbare Doku erstellen lassen kann.

    @TE Ich mach für alle meine Projekte inzwischen einfach git und wenns nur nen lokales Repository ist. Man hat immer wieder Commits, die klar sagen was los ist. Wenn man mal was verkackt kann man wieder auf nen anderen Stand zurück. Oder Stände vergleichen. Man kann den Entwicklungsprozess schön nach verfolgen mit z.B. feature-branches und hat immer wieder Releasebare zwischen schritte. Git muss man halt erstmal lernen, aber wenn man es mal halbwegs kann ists super.
    Für mich Persönich sehr wichtig ist git stash, hat mir schon so vieles einfacher gemacht ;)
    Ich wollte auch mal ne total überflüssige Signatur:
    ---Leer---

    jvbsl schrieb:

    @ErfinderDesRades: Kommentare im Code sind immer sinnvoll, wenn es etwas kompliziertere Algorithmen sind, oder die Algorithmen eben optimiert wurden, dass diese schwerer zu verstehen sind.
    Da sind wir völlig einig.
    Ich empfehle nur, auch den Umkehrschluss zu beachten: Trivial-Code zu kommentieren ist nämlich nicht sinnvoll.
    Sondern schadet der Übersicht, und beeinträchtigt meist sogar die notwendige Kommentation.

    Und mit "oberster MSDN-Verfechter" musst du was falsch verstanden haben.
    Und dass ich gegen Xml-Kommentare bin, hast du auch falsch verstanden.


    (Ist fast wie beim Trycatch-Thema: Alle sind einig, dass man nur Fehler fangen soll, die man auch behandeln kann, aber wenn ich empfehle, dass auch wirklich ernst zu nehmen, und die anderen Fehler eben nicht zu catchen gibts heisse Diskussion.
    Also die Parallelen zur TryCatch-Diskussion ist wirklich erstaunlich - da wird mir auch schnell unterstellt, ich sei gegen TryCatches.)
    Ich finde es ein wenig schade, dass du abseits deiner Ansichten keine anderen Ansichten als richtig erachtest, muss ich zugeben - und meine das nicht als Angriff, sondern als Aussage.
    Empfindung bzgl. Übersichtlichkeit sind sehr stark subjektiv geprägt, z.B. durch die Gewohnheit, die eigene "Historie" - die Lebenserfahrung in gewisser Hinsicht - oder durch die Art zu denken. Es gibt da meiner Ansicht nach nicht ein einziges Richtig oder Falsch.
    Zum Beispiel die Leerräume: Für dich machen sie den Code unübersichtlich, für mich haben sie zwei Wirkungen: Struktur - ich muss mir die logischen Trennungen nicht erst wieder herleiten - und die psychologische, dass klar ist, dass ich von meinem komplexen Gebilde nicht gleich erschlagen werde, weil es nur ein fetter Textblock ist.
    Die Kommentare zwischen den Codeabschnitten sind mir persönlich extrem wichtig. Habe ich den Kommentar verstanden, muss ich mir den Code gar nicht erst durchlesen, weil offensichtlich ist, was er macht und idR. auch wie es gemacht wird. Wenn es sich um einen Bug handelt, muss man dann halt nochmal drübergehen, ob das, was im Kommentar steht, Sinn macht und wenn, dann ob der Code das tut, was der Kommentar verlangt - und auch ob das in der Situation stimmig ist.

    Ich verstehe aber dennoch auch den Vorteil bei kompaktem Code: Man hat alles auf eimal im Blick und wird nicht von unnötigen Kommentaren abgelenkt. Und wenn es nicht mehr zu sagen gibt, als der Parametername hergibt, gibt es nicht mehr zu sagen.
    Empfinde ich für mich allerdings nicht angenehmer, als wenn alles vollständig beschrieben ist und somit Vollständigkeit suggeriert wird.

    Was bei mir häufig zum Problem wird, sind komplexere Algorithmen, die sich eben nicht nur über 50 Zeilen, sondern über ein paar hundert erstrecken können und die generisch sind. Durch die Generika und das ganze Abstrakte wird der Code so unleserlich, dass man ohne Kommentare nicht mehr auskommt. Da sucht und flucht man sich sonst an manchen Stellen zu Tode.

    (bzgl. deinem Kommentar: Ist mir btw. auch aufgefallen. Ich denke, man macht es immer so, wie es einem am sinnvollsten erscheint und über die Zeit eignet man sich dann hoffentlich einen Stil an, der sinnvoll ist und nicht nur für einen selbst, sondern auch für andere Leute, die sich den Code eines Tages zu Gemüte führen)

    Viele Grüße
    ~blaze~

    ~blaze~ schrieb:

    Ich finde es ein wenig schade, dass du abseits deiner Ansichten keine anderen Ansichten als richtig erachtest, muss ich zugeben - und meine das nicht als Angriff, sondern als Aussage.
    Für mich sind halt Argumente von entscheidender Bedeutung.
    Ist Vorgehensweise A besser begründet als Vorgehensweise B, dann ist entschieden.
    Ich kann da nicht von "Geschmacksache" reden - Geschmacksache ist, wenn Argumente sich die Waage halten, oder wenn das Thema garnet argumentierbar ist (ob nu einer Dark-Theme programmiert oder Blue).
    Ich täte euch bitten, das nicht so schlimm zu finden - ich kann nicht anders. Finde ich etwas begründet richtig, im Widerspruch zu etwas anderem, schlechter begründetem, dann finde ich das eben so wie ichs finde - ich kanns ja auch begründen.

    Und finde ich das andere besser begründet als meines, dann wechsel ich sofort meine Meinung!

    Was am Gesamteindruck nichts verändert: Vor und nach dem Meinungswechsel binnich derselbe Unsympath, der Geschmacksachen von Nicht-Geschmacksachen unterscheidet, und das auch sagt, insbes., wenn danach gefragt wird.
    Du musst aber unterscheiden: Du begründest hier, warum deine Meinung auf dich zutrifft. Dagegen sage ich nichts. Wogegen ich aber etwas sage ist, dass es daher auch die beste Lösung ist, weil das bedeuten würde, dass alle anderen Lösungen, die die Leute gefunden haben und nicht deiner entsprechen, nicht so gut sind, wie deine. Ich z.B. könnte mit deiner Lösung nicht arbeiten.

    Und übrigens: Ich versuche meist, Leuten gegenüber wertungsfrei aufzutreten und somit würde ich dem "derselbe Unsympath" widersprechen und dir sagen, dass ich absolut nichts gegen dich habe und auch nicht gegen deine Meinungen, Ansichten, etc. Zustimmung und Sympathie sind ja nicht zwangsweise miteinander verflochten. Wenn du mich jetzt einen ignoranten Idioten schimpfen würdest, der so dermaßen stur seine Meinung vertritt bzgl. der Offenheit gegenüber den Meinungen und Ansichten aller anderen, dann hätte ich damit eher Sympathieprobleme. ;)

    Viele Grüße
    ~blaze~

    ErfinderDesRades schrieb:

    Und mit "oberster MSDN-Verfechter" musst du was falsch verstanden haben.

    Dann halt statt MSDN eben Objektbrowser/IntelliSense informationen. Macht jetzt auch nicht so den Unterschied.
    Ich wollte auch mal ne total überflüssige Signatur:
    ---Leer---

    ~blaze~ schrieb:

    Du begründest hier, warum deine Meinung auf dich zutrifft. Dagegen sage ich nichts. Wogegen ich aber etwas sage ist, dass es daher auch die beste Lösung ist, weil das bedeuten würde, dass alle anderen Lösungen, die die Leute gefunden haben und nicht deiner entsprechen, nicht so gut sind, wie deine.
    Ja, das ist tatsächlich meine Meinung - ist das denn so unerhört?
    Ich bin der Meinung, meine Meinung ist die beste, und alle anderen Meinungen sind folglich weniger gut - tatsächlich. Denn wäre eine Meinung besser als meine, würde ich sie ja sofort übernehmen.
    Dass ich nicht alles weiß, und dass ich mich irren kann wie jeder andere auch, ist dabei kein Problem, sondern ist sogar Fundament dieser Einstellung.
    Anders ausgedrückt: Ich versuche, entweder zu überzeugen oder mich überzeugen zu lassen.

    Ich sag doch - ich kann nicht anders ;)

    Tatsächlich glaube ich ja, jedes (ehrlichen) Menschen Meinung zu jedem Thema folgt diesem Prinzip. Oder würdest du deine Meinung vertreten gegen eine andere, von der du der Meinung bist, sie sei besser?

    Ich find diese Haltung auch nicht schlimm. Evtl. oktroiere ich sogar weniger als andere. Ich lese halt Sätze wie

    RodFromGermany schrieb:

    Prozeduren, Properties usw. kommentieren ist ein Muss
    , bin anderer Meinung, stelle meine Meinung zur Verfügung und begründe sie auch.

    Was der Leser damit macht ist ihm doch überlassen. Ich bin strikter Undogmatiker und Nicht-Verfechter, allenfalls Verfechter folgenden Paulus-Dogmas:
    "Prüfet aber alles, und das Gute behaltet..."

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