Laden...

Dokumentation einer Anwendung

Erstellt von cware vor 16 Jahren Letzter Beitrag vor 16 Jahren 4.829 Views
C
cware Themenstarter:in
15 Beiträge seit 2007
vor 16 Jahren
Dokumentation einer Anwendung

Hallo,

muss für meinen evtl. neuen Arbeitgeber eine Probearbeit erstellen, in der ich eine kleine Windowsapplikation erstellen und dokumentieren muss.

Die Anwendung habe ich geschrieben, UML-Diagramme habe ich ebenfalls erstellt - doch bei der schriftlichen Dokumentation habe ich so meine Schwierigkeiten.

Werde normalerweise alle Methoden und Klassen beschrieben oder wie stellt man sowas professionell an?

Es soll eine technische Dokumentation werden - die den Anforderungen von Informatiker und nicht Informatikern gerecht wird.

kann mir jenamd Tipps geben wie ich sowas realisieren kann?

cware

K
124 Beiträge seit 2006
vor 16 Jahren

Hallo cware,

sämtliche Klassen, Nethoden etc. sollten bereits inline -am besten per XML Kommentare - dokumentiert werden. VS2005 kann daraus zwar nur ein XML File erstellen, allerdings gibt es tools, die aus dem XML eine Dokumetation im Stil der MSDN erstellen. Bekannt und am öftesten benutzt werden glaube ich NDoc und Doxygen

lg

kaloon

49.485 Beiträge seit 2005
vor 16 Jahren

Hallo cware,

Werde normalerweise alle Methoden und Klassen beschrieben oder wie stellt man sowas professionell an?

das ist durchaus sinnvoll. Verwende dazu die C#-XML-Kommentare, die mit /// eingeleitet werden. Das wäre dann die Dokumentation des Programmcodes auf hoher Ebene. Weitere Kommentare des Programmcode auf Ebene eines oder meherer Statements ist zusätzlich wünschenswert. Außerdem könntest du zusätzlich zu UML eine textuelle Dokumentation erstellen, die das Design der Anwendung beschreibt.

herbivore

T
18 Beiträge seit 2007
vor 16 Jahren

Hallo cware,
mit UML Diagrammen und mit Doxygen generierten Klassen/Methoden Telefonbuch hast Du eigentlich schon das was normalerweise zur Dokumentation gehört.

Meistens wird eine Dokumentation der Use Cases vergessen bzw. ausgelassen. Da Du es bestimmt besser machen willst, beschreib einfach was jeder einzelne Anwendertyp mit deiner Anwendung eigentlich machen kann.

lg Thomas

Hi ha ho, jetzt simmer widder froh 🙂

476 Beiträge seit 2004
vor 16 Jahren

hallo cware,

ich finde ein gutes Beispiel für Inline-Dokumentation sieht man hier: Providerunabhängige Datenzugriffskomponente. Ich vermute die Dokumentation soll mitunter zeigen ob du den Sachverhalt (oder den Sinn des Codes) in Worte fassen kannst, also, gut auf Formulierung und Rechtschreibung achten. Keine Romane aber auch keine unverständlichen Kommentarbrocken. Das wäre mein Tipp.

-yellow

Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).

Mein Blog: Yellow's Blog auf sqlgut.de

T
18 Beiträge seit 2007
vor 16 Jahren

Hallo yellow,
wie man doch unterschiedlicher Ansicht sein kann. Ich finde die Beschreibung schlicht weg grässlich:


 public class Database
    {
        /// <summary>
        /// Speichert Änderungen an einer Tabelle in der Datenbank.
        /// </summary>
        /// <param name="factory">Fabrik des Datenanbieters</param>
        /// <param name="connectionString">Verbindungszeichenfolge</param>
        /// <param name="table">Tabelle mit Änderungen</param>
        public static void Update(DbProviderFactory factory, string connectionString, DataTable table)

Wenn die Methode Database.Update heißt, sollte sie wirklich in der Datenbank etwas ändern, daß factory eine Fabrik, connectionString eine Verbindungszeichenfolge ist, sollte klar sein.

Aber trotzdem gibt es Auftraggeber, die genau solche Dokumentation haben wollen 🙂

Grüße Thomas

Hi ha ho, jetzt simmer widder froh 🙂

476 Beiträge seit 2004
vor 16 Jahren

hallo ThomasGawehns,

Original von ThomasGawehns
Wenn die Methode Database.Update heißt, sollte sie wirklich in der Datenbank etwas ändern

...was sie ja auch tut 😄.

-yellow

Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).

Mein Blog: Yellow's Blog auf sqlgut.de

T
18 Beiträge seit 2007
vor 16 Jahren

Hallo cware, hallo Yellow,

ich habe mir den Source zur Update Methode einmal genauer angesehn und es ist eigentlich ein genaues Gegenspiel von guter Dokumentation:


        /// <summary>
        /// Speichert Änderungen an einer Tabelle in der Datenbank.
        /// </summary>
        /// <param name="factory">Fabrik des Datenanbieters</param>
        /// <param name="connectionString">Verbindungszeichenfolge</param>
        /// <param name="table">Tabelle mit Änderungen</param>
        public static void Update(DbProviderFactory factory, string connectionString, DataTable table)
        {
            // Datenbankverbindung erzeugen
            using (DbConnection connection = factory.CreateConnection())
            {
                // Verbindungszeichenfolge übernehmen
                connection.ConnectionString = connectionString;

                // SELECT-Befehl zusammensetzen
                StringBuilder statement = new StringBuilder();
                statement.Append("SELECT * FROM ");
                statement.Append(table.TableName);
                statement.Append(" WHERE 0=1");

                // Datenbankbefehl erzeugen
                DbCommand selectCommand = factory.CreateCommand();
                selectCommand.Connection = connection;
                selectCommand.CommandType = CommandType.Text;
                selectCommand.CommandText = statement.ToString();

                // Datenadapter erzuegen
                DbDataAdapter adapter = factory.CreateDataAdapter();
                adapter.SelectCommand = selectCommand;
                adapter.AcceptChangesDuringUpdate = true;

                // Befehlsgenerator erzeugen
                DbCommandBuilder builder = factory.CreateCommandBuilder();
                builder.ConflictOption = ConflictOption.CompareAllSearchableValues;
                builder.DataAdapter = adapter;

                // Änderungen übernehmen
                adapter.Update(table);       
            }          
        }

Ich würde dazu anmerken:

  1. Die Tabelle in der Datenbank wird anscheinend nicht geändert, sondern es werden nur neue Zeilen eingetragen.

  2. Die Select Abfrage wird gar nicht erklärt. Das Result sollte immer leer sein (1 = 0). Warum braucht es diese Abfrage? Funktioniert das mit jedem Datenbank Provider?

  3. Es wird ein Adapter erzeugt, dieser wird einem CommandBuilder zugewiesen und dann wird eine Methode des Adapters und nicht des CommandBuilders aufgerufen. Hier wäre ein Hinweis gut, daß die Zuweisung wirklich nötig ist, ansonsten könnte man diese ja auch weglassen.

Grüße Thomas

Hi ha ho, jetzt simmer widder froh 🙂

476 Beiträge seit 2004
vor 16 Jahren

hallo cware, hallo ThomasGawehns

Original von ThomasGawehns
Ich würde dazu anmerken:

  1. Die Tabelle in der Datenbank wird anscheinend nicht geändert, sondern es werden nur neue Zeilen eingetragen.

Jetzt habe ich verstanden was du meintest, stimmt, würde ein "in" statt einem "an" stehen, wäre es weniger missverständlich.

Original von ThomasGawehns
2. Die Select Abfrage wird gar nicht erklärt. Das Result sollte immer leer sein (1 = 0). Warum braucht es diese Abfrage? Funktioniert das mit jedem Datenbank Provider?

Gut, in dem Kommentar fehlt noch der Hinweis wofür es gebraucht wird, allerdings bedingt der CommandBuilder einem Schema um seine Commands erzeugen zu können. (1=0) funktioniert afaik immer (nicht wie Top 0, Limit usw.)

Original von ThomasGawehns
3. Es wird ein Adapter erzeugt, dieser wird einem CommandBuilder zugewiesen und dann wird eine Methode des Adapters und nicht des CommandBuilders aufgerufen. Hier wäre ein Hinweis gut, daß die Zuweisung wirklich nötig ist, ansonsten könnte man diese ja auch weglassen.

Auch das bedingt sich durch ADO.NET

Man sieht hier wie sich die Meinung zu gutem und schlechtem Dokumentierstil unterscheiden können, was im allgemeinen von der persönlichen Erwartung an die Dokumentation abhängt.

Ich lese Dokumentationen am liebsten in eben diesem von mir vorgeschlagenen Stil, denn wenn ich den Code überfliege interessiert mich nur Blockweise was dort implementiert ist. Warum ich jetzt (1=0) Abfrage, oder warum der DataAdapter dem CommandBuilder zugewiesen wird, das sind Dinge die mich nur so lange interessieren bis ich mit dem Teil des Frameworks vertraut bin, ab dann empfinde ich es nur noch lästig und überflüssig.

-yellow

Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).

Mein Blog: Yellow's Blog auf sqlgut.de

F
10.010 Beiträge seit 2004
vor 16 Jahren

Diese unsägliche (1=0) hat sich mal jemand ausgedacht, der die Funktionsweise
des DataAdapters nicht ganz verstanden hat, und ganz sicher gehen wollte.

Es ist unnötig, da zum holen das Schemas sowieso keine Tabellendaten übertragen werden.

Irgendwie hat es sich aber wie ein guter Virus einfach weiterverbreitet.

@ThomasGawehns:
Du solltest dringend die funktionsweise der angesprochenen ADO.NET Objekte
nachlesen.

49.485 Beiträge seit 2005
vor 16 Jahren

Hallo FZelle,

der Code ist von Rainbird, nicht von ThomasGawehns.

herbivore

F
10.010 Beiträge seit 2004
vor 16 Jahren

Das hatte ich gesehen, aber thomas scheint die funktionalität des Sources gründlichst missverstanden zu haben.
Auch scheint ihm nicht bekannt zu sein was die ADO.NET Objekte machen.

Siehe Kommentar zum Commandbuilder.

T
18 Beiträge seit 2007
vor 16 Jahren

Hallo FZelle,
es geht hier um Dokumentation und Kommentare. Diese sollten ja die "funktionalität des Sources" beschreiben. Oder sie sind eine Verschwendung von Speicherplatz und Zeit.

lg Thomas

Hi ha ho, jetzt simmer widder froh 🙂

476 Beiträge seit 2004
vor 16 Jahren

Original von FZelle
Diese unsägliche (1=0) hat sich mal jemand ausgedacht, der die Funktionsweise
des DataAdapters nicht ganz verstanden hat, und ganz sicher gehen wollte.

Stimmt, ist unnötig... danke für das aufmerksam machen.

Ansonsten, lasst uns lieber wieder den Thread über Dokumentation und Kommentare fortführen und cware Anregungen geben wie sie dokumentieren könnte.

-yellow

Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).

Mein Blog: Yellow's Blog auf sqlgut.de

3.728 Beiträge seit 2005
vor 16 Jahren

Als Urheber dieses so scheinbar grausam dokumentierten Codeabschnitts, möchte ich dazu auch etwas sagen.

Original von ThomasGawehns
Ich würde dazu anmerken:

  1. Die Tabelle in der Datenbank wird anscheinend nicht geändert, sondern es werden nur neue Zeilen eingetragen.

Natürlich ändert Update die Datenbank! Meine Methode aktualisiert eine Tabelle auf dem Datenbankserver. Die auszuführenden Änderungen (Neue Datensätze, Löschungen und Aktualisierungen) werden aus der übergebenen DataTable bezogen und über einen Datenadapter ausgeführt. Die benötigten UPDATE, INSERT und DELETE SQL-Befehle erzeugt ein CommandBuilder automatisch. Also behaupte bitte nicht, die Update-Methode würde die Datenbank nicht ändern.
Meine Dokumentation "Speichert Änderungen an einer Tabelle in der Datenbank." beschreibt genau, was die Update-Methode tut.

Original von ThomasGawehns
2. Die Select Abfrage wird gar nicht erklärt. Das Result sollte immer leer sein (1 = 0). Warum braucht es diese Abfrage? Funktioniert das mit jedem Datenbank Provider?

Diese Abfrage dient nur dazu, ein leeres Resultset mit den korrekten Spaltennamen für den CommandBuilder zu bekommen. Dieser benötigt diese Metadaten, um davon INSERT, UPDATE und DELETE SQL Befehle zu erzeugen. Laut Microsoft benötigt der CommandBuilder ein gültiges SELECT-Statement:

Original von Visual Studio-Hilfe
SqlDataAdapter generiert nicht automatisch die Transact-SQL-Anweisungen, die zum Abgleichen von Änderungen an einem DataSet mit der zugeordneten Instanz von SQL Server erforderlich sind. Sie können aber ein SqlCommandBuilder-Objekt erstellen, um Transact-SQL-Anweisungen für das Aktualisieren einzelner Tabellen automatisch zu generieren, indem Sie die SelectCommand-Eigenschaft von SqlDataAdapter festlegen. Anschließend werden alle zusätzlichen, von Ihnen nicht festgelegten Transact-SQL-Anweisungen durch den SqlCommandBuilder generiert.

Zu erklären dass ein SelectCommand für die korrekte Funktionsweise des CommandBuilders notwendig ist, ist nicht Aufgabe meiner Dokumentation. Die Code-Kommentare sollen dem "Leser" des Codes vermitteln, was ein bestimmter Codeabschnitt tut. Sie sollen nicht Konzepte des eingesetzten Frameworks erklären. In diesem Fall erzeugt der Code einen SELECT-Befehl. Und genau das steht auch im Kommentar.

Original von ThomasGawehns
3. Es wird ein Adapter erzeugt, dieser wird einem CommandBuilder zugewiesen und dann wird eine Methode des Adapters und nicht des CommandBuilders aufgerufen. Hier wäre ein Hinweis gut, daß die Zuweisung wirklich nötig ist, ansonsten könnte man diese ja auch weglassen.

Wenn eine Zuweisung nicht nötig ist, lasse ich sie gleich weg! Ich muss in meinen Kommentaren nicht erklären, warum ich eine Zuweisung mache oder nicht. In diesem Fall gehört die Zuweisung zum Code-Block "Befehlsgenerator erzeugen". Da es sich um einen Block handelt, vermittelt der Kommentar dem "Leser", dass der Ganze Block dafür da ist, den Befehlsgenerator zu erzeugen. Nach diesem Block kann man also davon ausgehen, dass der Befehlsgenerator fertig erzeugt ist.

T
18 Beiträge seit 2007
vor 16 Jahren

Hallo Rainbird,
Du hast vollkommen recht, Deine Kommentare sind für Dich und Deinen Source.

Bleibt die Frage warum Du überhaupt Kommentare einfügst, z.B. "// SELECT Befehl zusammensetzen"? Aber jeder hat seinen eigenen Stil.

lg Thomas

Hi ha ho, jetzt simmer widder froh 🙂

3.728 Beiträge seit 2005
vor 16 Jahren
Kommentare

In den meisten Fällen sind die Kommentare für den, der auch den Code erstellt (den der muss den Code auch weiterentwickeln und warten). Wenn ich meinen Code ein halbes Jahr später anfassen muss, freue ich mich immer sehr über die Kommentare.
Auch wenn mal jemand anderes meinem Code lesen muss, werden sie hilfreich sein!

Kommentare haben auch eine Art Gruppierungsfunktion. Man beschriftet damit einen Block Code, der etwas bestimmtes tut. Solche beschrifteten Code-Blöcke sind einfach zu lesen.

F
10.010 Beiträge seit 2004
vor 16 Jahren

@ThomasGawehns:
Ich gebe Dir recht, das kein kommentar besser ist als sinnlose kommentare,
die nur den Bildschirm zumüllen und dadurch den Blick aufs wesentliche versperren.

Aber deine 3 Punkte zeigen, das Du nicht den blassesten Schimmer hast,
wie ADO.NET funktioniert.
Sonst hättest Du das nicht so geschrieben.

S
489 Beiträge seit 2007
vor 16 Jahren

Hi!

Über "die richtige Dokumentation" lässt sich immer streiten. Firmen die Wert auf eine gute Dokumentation legen geben dafür auch entsprechende Richtlinien aus. Je nach dem für wen die Dokumentation dann sein soll gestalten sich dann diese Richtlinien.

Die Dokumentation von Rainbird finde ich persönlich ganz gut, nur würde ich zu

Original von Rainbird
"Speichert Änderungen an einer Tabelle in der Datenbank."

noch einen entsprechenden Bezug hinzufügen. Meiner Meinung nach fehlt hier was für Änderungen gespeichert werden. Ist dieser Bezug vorhanden passt der missverständliche Methodenname sicher auch besser.

Ich denke der Bezug den ich hier anspreche wird auch durch den Rest des Programmes gegeben sein, aber wenn man ihn als einzelne Methode ansieht (wie es hier der Fall ist) ist die Dokumentation nicht wirklich hilfreich.