Dokumentieren bestehenden Code

Question

Ich habe gerade einen Heroic-Shop beigetreten. Der Code scheint sauber und hochwertig zu sein, aber es gibt keine Dokumentation, von der man sprechen könnte. (Der Code wurde von einer kleinen Gruppe geschrieben und gepflegt). Daher müssen neue Ingenieure von der Quelle aus neu konstruieren, um das Design zu bestimmen. Während das Projekt von einem kleinen (3) Team zu einem größeren Team übergeht, möchte ich meine Bemühungen dokumentieren, die Anwendungen zu lernen, damit die nächste Stelle sie schneller lernen kann.

Eine schnelle Suche nach "Dokument vorhanden" + Anwendung | Code ergibt nicht viel. Ich bin mir sicher, dass dies eine häufige Frage ist, daher könnte der Hinweis auf eine andere Diskussion die beste sein.

Irgendwelche Vorschläge?

Answer 1

Welche Sprache? Abhängig von der Sprache könnte etwas wie doxygen sehr hilfreich sein.

Answer 2

Ein weiterer einfacher Ausgangspunkt ist ein Wiki. Das Dokumentieren oder das Diagrammieren der übergeordneten Struktur des Systems/der Anwendung, so dass jeder einen anständigen Startpunkt hat, sollte Priorität haben, und ein Wiki ist eine bequeme Möglichkeit, die Informationen dorthin zu bekommen. (Ich wäre überrascht, wenn es gab keine Dokumentation auf dieser Ebene von den Original-3, aber ich wette, dass sie etwas whomp könnten nützlich sehr schnell ...)

Answer 3

VSdocman (http://www.helixoft.com) ist ausgezeichnetes Werkzeug für die Dokumentation erzeugen für C# und VB.NET. Sie haben auch ein Tool für VB6. Sie können die 14-Tage-Testversion herunterladen. Der Preis begann von 229 für .NET-Version und 79 für VB6.

Answer 4

Sie können einige Ihrer Dokumentationen in Form von automatisierten Tests durchführen. Dann werden Sie (a) verifizieren, dass der Code wirklich funktioniert so arbeiten, wie Sie es verstehen, und (b) eine Reihe von Regressionstests aufbauen, um Sie wissen zu lassen, wenn Sie später etwas brechen (z. B. weil Sie das nicht erkennen Das Ändern von X wird einen Nebeneffekt in Y verursachen - sehr möglich sogar in Code, den Sie kennen.

Wenn Sie nicht wissen, wie Sie mit dem Hinzufügen von Tests zu bestehendem Code beginnen können, holen Sie sich das ausgezeichnete Buch von Michael Feathers "Working Effectively with Legacy Code".

Für (leicht) lesbare und skimmbare Dokumentation können Fit und FitNesse menschenlesbare, aber ausführbare Tests erstellen, insbesondere wenn die Anforderungen in einem Raster dargestellt werden können (diese Eingänge -> diese Ausgänge).

Answer 5

Um zu unterstützen, was Jeff K. sagte, würde ich mit einem Wiki gehen, mit privs so weit wie möglich verteilt (ideal auch für Ihre Benutzer). Sobald die Leute wissen, dass es losgeht, reicht es oft aus, einen Stub für jedes Programm zu erstellen, um mehrere Iterationen von Aktualisierungen zu katalysieren, was in einer ziemlich vollständigen Dokumentation überraschend schnell endet. Ingenieure mögen es hassen, Dinge zu dokumentieren, aber wir können nicht widerstehen, etwas zu reparieren, was wir falsch sehen.

Im schlimmsten Fall enden Sie revisionskontrollierte Dokumente, die niemand außer Ihnen jemals bearbeitet. Das ist nicht schlimmer als jetzt.

Answer 6

Je nachdem, wie komplex der Code ist, habe ich ein paar Dinge getan.

Sie wollen wahrscheinlich jede Methode/Funktion/Objekt/was auch immer (Sie sprachen keine Sprache) und versuchen zu verstehen, was es tut. Wenn Sie etwas haben, das Sie mehr als eine Minute braucht, um zu verstehen, herauszufinden, was Sie nicht verstanden haben und einen Kommentar schreiben, damit Sie das nächste Mal nicht in dieser Minute brauchen.

Zu verstehen, wie alle Teile zueinander in Beziehung stehen, kann schwierig sein, wenn das Design nicht sehr gut ist.Das Drucken der Debug-Ausgabe am Eingang/Ausgang jeder Routine und das Verwenden von Stack-Dumps kann hilfreich sein, um zu sehen, wie Sie einen Platz erhalten haben. Ein Debugger kann großartig sein, um das herauszufinden.

Ein letztes Werkzeug, das ich wirklich nützlich fand, ist ein Profiler. Ich hatte ein kostenloses Profiler-Plug-in für Eclipse (ich vergesse den Namen, aber ich glaube nicht, dass es viele gibt), das ein beeindruckendes Sequenzdiagramm für jeden Code erstellen würde, den es durchlaufen hat. Dies könnte das beste Werkzeug sein, das ich jemals gesehen habe, um zu verstehen, was der Code macht. Es war ein bisschen schwierig, sich zu dieser Zeit einzurichten, aber bleib dran, es ist machbar und es ist es wert.

Ich habe den Profiler eingeschaltet, eine Taste gedrückt/eine Aufgabe ausgeführt und dann den "Run" für diese Taste gespeichert.

Ich filterte Klassen heraus, die trivial waren und es in eine halbwegs vernünftige Größe brachten (einige waren 2 Seiten, ein Sequenzdiagramm nahm 4 x 6 Blatt Papier zum Drucken (Querformat)). Ich nahm sie alle zusammen auf und legte sie auf meine Würfelwand und studierte/dokumentierte die Hölle aus diesem Ding.

Sequenzdiagramme rocken, wenn Sie richtig gemacht werden, übrigens. Wenn Sie versuchen, etwas Code zu verstehen, und Sie keine Sequenzdiagramme verwenden, schauen Sie sich diese an. Ich denke, sie sind wahrscheinlich das nützlichste Designdokumentationswerkzeug, das ich gesehen habe.

Answer 7

Wenn der Code nur wenige oder zu wenige Kommentare enthält, hat Doxygen einen begrenzten Wert. Es kann jedoch weiterhin verwendet werden, um Ihnen eine Vorstellung von der Codestruktur und den Abhängigkeiten zu geben. (Dinge wie ein Profiler sind großartig, um das Verhalten zu verstehen.) Ich finde Bilder hilfreich zum Verständnis von Abhängigkeiten und führe den Code normalerweise durch ein UML-Werkzeug, um den Entwurf zurückzuentwickeln. Sie können ähnliche Klassendiagramme mit Graphviz erstellen, die sich sehr einfach in Doxygen integrieren lassen (auch für nicht objektorientierten Code).