[Gelöst] Dokumentation im Sourcecode: Vorschläge?

Hallo,

das Topic ist vielleicht ein wenig merkwürdig, aber es interessiert mich welche unterschiedlichen "Styles" (Art, Umfang, Formatierung) ihr in Sachen Sourcecode Dokumentation (Änderungen, Neues, gelöschtes) habt. Über die Boardsuche habe ich nichts gefunden.

Alles im Documentation-Trigger? Oder vieles direkt dort wo "verändert" wurde? Wie verfahrt ihr mit Änderungen an Forms oder Reports?

Welche Angaben werden gemacht? (Entwickler, Datum, Was, Warum, Wie?, Ausführlichkeit)

Über Antworten würde ich mich freuen.

Viele Grüße,
Janosch

Zuletzt geändert von janosch am 14. April 2009 10:44, insgesamt 1-mal geändert.

bei uns läuft das so:

Übersicht der Änderungen im Doku() Header, mit Datum, kurzer Erläuterung und Projektbezugscode und Codeänderungen d.h. Codeergänzungen werden mit

Code:

///// Firma XY. dayscot /////
code
code
//////Firma XY. dayscot Änderung Ende ///

gekennzeichnet.

Bei uns ist es so:
Im Doku-Trigger steht allgemein was geändert wurde. In den anderen Triggern werden Änderungen mit "// -xxx" und // +xxx" gekennzeichet (xxx steht für die Änderungsnr. welche im Doku-Trigger genannt wird). Dadurch ist es möglich, Änderungen rückgängig zu machen und nachzuvollziehen, wieso eine Änderung durchgeführt wurde.

Auch, wenn es Unterschiede in den Details gibt, so ist das Prinzip doch immer gleich:

• Im Documentation Trigger stehen die eindeutige Änderungsnummer, Datum, Entwickler-Kürzel und kurze (einzeilige) Beschreibung der Änderung
  Beispiel:
  TL5.00:01 09.04.2009 TL Neues Feld 54711 eingefügt
• Neue/geänderte Felder werden mit der Änderungsnummer im Description-Property gekennzeichnet
• Neue/geänderte Schlüssel werden vollständig im Documentation-Trigger genannt (alte sowie neue Version)
• Änderungen am C/AL-Code werden mit einem jeweiligen Start-/End-Tag dokumentiert
  Beispiel:
  // > TL5.00:01 >>>
  [...]
  // < TL5.00:01 <<<
• Standard-Code wird niemals gelöscht, sondern nur auskommentiert
  (Gilt auch für Branchencode, welcher durch Individualanpassungen geändert werden muss.)
• Das geänderte Objekt bekommt in der Versionsliste eine eindeutige (aufgaben- und entwicklerunabhängige) Kennzeichnung.
  Beispiel:
  NAVW15.00,TL5.00

Um Timos sehr ausfürhliche Beschreibung noch zu erweitern:

• Nach Anpassung des Version Tags sollte das Modified Flag entfernt und das Änderungsdatum/-uhrzeit der geänderten Objekte normiert werden (z. b. 12:00:00).
• Viele Informationen und Richtlinien hierzu gibt der NAV Style Guide vor (Dokumente C/AL Programming Guide und Application Designer's Guide).
• Die Ausführliche Änderungsbeschreibung sollte nicht im Dokumentation Trigger eingefügt werden. Hierfür wird eine eigene Technische Dokumentation empfohlen.

Guten Morgen NAV-IANER,

vielen Dank für die zahlreichen Rückmeldungen.

• Die Ausführliche Änderungsbeschreibung sollte nicht im Dokumentation Trigger eingefügt werden. Hierfür wird eine eigene Technische Dokumentation empfohlen.

Finde ich wichtig, da sich im Dokumentations Trigger anscheinend kurz gefasst werden soll. Bietet sich für die technische Dokumentation vielleicht ein Wiki an?

Darüber hinaus stellt sich mir die Frage nach "grafischen" Änderungen. Werden die ebenfalls im Dokumentations Trigger hinterlegt? Z.B.

Code:

Bei Feld XXXXX width vergrößert, da sonst Nummernserie auf Report/Ausdruck abgeschnitten

Viele Grüße,
Janosch

Bietet sich für die technische Dokumentation vielleicht ein Wiki an?

Ein Wiki wäre eine Möglichkeit. Hierfür gibt es keine definierte Richtlinie - lediglich gibt es Vorgaben/Empfehlungen, was eine solche Doku enthalten sollte.
Hier kann ich das Dokument Navision Attain Solution Development von 2001 empfehlen.

Darüber hinaus stellt sich mir die Frage nach "grafischen" Änderungen. Werden die ebenfalls im Dokumentations Trigger hinterlegt?

Grundlegend sollten Änderungen an Properties Dokumentiert werden. Bei Design-Änderungen würde dies allerdings den Rahmen sprengen, darum wird das oft nicht so detailliert dokumentiert.

Hier kann ich das Dokument Navision Attain Solution Development von 2001 empfehlen.

Gucke ich mir an.

Grundlegend sollten Änderungen an Properties Dokumentiert werden. Bei Design-Änderungen würde dies allerdings den Rahmen sprengen, darum wird das oft nicht so detailliert dokumentiert.

Eine Änderung ob z.B. eine Nummernserie angezeigt werden kann oder nicht, halte ich für Grundlegend und Erwähnenswert

Vielen Dank noch mal an alle für die Hinweise!

Gruß Janosch

• Nach Anpassung des Version Tags sollte das Modified Flag entfernt und das Änderungsdatum/-uhrzeit der geänderten Objekte normiert werden (z. b. 12:00:00).

Dabei ist zu beachten, dass in der ZUP Datei als Maßstab für eine Objektänderung nur die Uhrzeit herhält. Sprich einschneidende Änderungen in z.B. einer Form (andere Tabelle) könnten unter Umständen zu ungewollten Seiteneffekten führen, sofern die alte Uhrzeit und die neue identisch sind.