Wie dokumentiere ich richtig?

[fkerber]

Hi!

Innerhalb der nächsten 1 1/2 Jahre werde ich eine besondere Lernleistung im Fach Informatik anfertigen. Natürlich muss dann sämtlicher Code etc. dokumentiert werden. Da die schriftliche Dokumentation nur 25 Seiten umfassen darf (!), kann man da natürlich nicht alles reinbringen.

Also folgende Fragen:

• Wie dokumentiere ich den Quelltext in den *.pas richtig?
• Was bringe ich in die schriftliche Dokumentation ein?
• Wie bringe ich das da ein?

Danke für die Infos.


Ciao Frederic

[HW764]

Also als erstes schriebst du vor jeder Code Kategorie, was diese Kategorie macht und welche Units verwendet werden. Danch schriebst du, wann du es als letztes mal geändert hast. Bei jeder wichtigen Zeile schreibst du einen Kutzen Kommentar.
Wichtig! Am anfang der Unit immer schreiben, dass es von dir ist! "2004 (C) by fkerber"

Beispiel:

Delphi-Quellcode:

// Kategorie: Messages
// Units: -
// Letzte änderung 7.8.2004
procedure TForm1.Button1Click(Sender: TObject);
begin
showmessage ('Das ist ein Test!') //Message
end;

In der .dpr schreibst du eine Kurze Erklärung deines Programms hinein.
(z.B. Was es macht, mit was es Programmiert wurde...)

So würde ich es erwarten!

Gruss HW764


Komplettes Beispiel:

Delphi-Quellcode:

///////////////////////////////////////////
// (C) 2004 by Kevin Nieberle            //
////////////////////////////////////////////////////////
//Dieses Programm erstellt und zeigt Bergspitzen auf  //
//einem Image an.                                     //
////////////////////////////////////////////////////////
unit Unit1;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls, Buttons, ExtCtrls;

type
  TForm1 = class(TForm)
    BitBtn1: TBitBtn;
    bild: TImage;
    procedure BitBtn1Click(Sender: TObject);
  private
    { Private-Deklarationen }
  public
    { Public-Deklarationen }
  end;

var
  Form1: TForm1;

implementation

{$R *.dfm}


// Kategorie: Createblackstroke
// Units: -
// Letzte änderung 7.8.2004
procedure TForm1.BitBtn1Click(Sender: TObject);
var x:integer;              // Variabeln definieren
    steigung,y:real;
    plusminus:boolean;
    auswahl:integer;
    bergspitzen:integer;
const berg = 50;            //constante festlegen
begin
   bild.Picture.Free;        
   bild.Picture := tpicture.Create;   //erstellt tpicture
   randomize; 
   y := random(bild.Height div 2); //Startpunkt
   steigung := random(20) / (random(30)+1);   //Startsteigung 
   bergspitzen := random(berg); //Wahrscheinlichkeit von vielen Bergspitzen 
for x := 1 to bild.Width do
  begin 
    auswahl := random(bergspitzen+1); //Erstellt jedesmal ein anderes Ergebnis
      if auswahl = bergspitzen then 
        if plusminus = true then
         begin 
          plusminus := false; 
          steigung := random(10) / (random(30)+1);
        end 
      else 
        begin
          plusminus := true; 
          steigung := random(10) / (random(30)+1); 
        end;
      if plusminus = true then 
        begin 
          y := y + steigung + (random(2)-1);
          if y > bild.Height-50 then 
            y := bild.Height-50; 
          if y < 0 then
            y := 0; 
        end                                           // u.s.w
      else 
        begin
          y := y - steigung - (random(2)-1);
          if y < 0 then
            y := 0;
          if y > bild.Height-100 then
            y := bild.Height-100;
        end;
   bild.Canvas.Polygon([point(x,bild.Height),point(x,bild.Height-round(y))]);
  end;
  bild.repaint; // Wichtig! Ein Repaint machen!

end;

end.

[fkerber]

Hi!

Danke für deinen Beitrag.


Ciao Frederic

[HW764]

Ich hoffe ich konnte dir helfen!
So kannst du auch verwirrungen verhindern.
Ich weiss dass es lange geht, aber ich würde es von
Anfang an so machen.

Gruss HW764

PS: Habe noch ein Beispiel eingefügt!

[fkerber]

Hi!

Danke auch für dein Beispiel.

Ciao Frederic

[Luckie]

Wie der Stil der Kommentare aussieht ist so ziemlich Geschmackssache. Bei mir würde das so aussehen:

Delphi-Quellcode:

{************************************************************}
{                                                            }
{             Demo OpenDlg erweitern - Version 1.0           }
{                                                            }
{               Copyright (c) 2004 Michael Puff              }
{                                                            }
{  When I die I want 'Hello, world' carved on my headstone.  }
{                                                            }
{************************************************************}

unit Unit1;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls;

type
  TForm1 = class(TForm)
    OpenDialog1: TOpenDialog;
    Button1: TButton;
    procedure Button1Click(Sender: TObject);
  private
    { Private declarations }
    procedure OpenDlgOnShow(Sender: TObject);
    procedure OpenDlgOnClose(Sender: TObject);
  public
    { Public declarations }
  end;

var
  Form1: TForm1;

implementation

{$R *.dfm}

////////////////////////////////////////////////////////////////////////////////
//
//  TForm1.OpenDlgOnShow
//
//    OnShowEventHandler des Dialoges
//    Edit auf Dialog plazieren
//

procedure TForm1.OpenDlgOnShow(Sender: TObject);
var
  hParent: THandle;
  rect: TRect;
  hEdit: THandle;
begin
  // OpenDialog1.Handle ist irgendwie das falsche :?
  hParent := GetParent(OpenDialog1.Handle);
  // Position und Größe ermitteln
  GetWindowRect(hParent, rect);
  // Dialog vergrößern für Edit
  SetWindowPos(hParent, 0, 0, 0, rect.Right - rect.Left, rect.Bottom - rect.Top
    + 25, SWP_NOMOVE);
  // Edit erzeugen, ID = 101
  hEdit := CreateWindowEx(WS_EX_CLIENTEDGE, 'EDIT', '', WS_VISIBLE or WS_CHILD,
    195, rect.Bottom - rect.Top - 27, 150, 20, hParent, 101, 0, nil);
  if hEdit = 0 then
    RaiseLastOSError;
end;


////////////////////////////////////////////////////////////////////////////////
//
//  TForm1.OpenDlgOnClose
//
//    OnCloseEventHandler des OpenDialoges
//    eigenes Edit auslesen
//

procedure TForm1.OpenDlgOnClose(Sender: TObject);
var
  hParent: THandle;
  hEdit: THandle;
  Buffer: PChar;
  len: Integer;
begin
  hParent := GetParent(OpenDialog1.Handle);
  // Handle des Edits ermitteln, ID = 101 siehe oben
  hEdit := GetDlgItem(hParent, 101);
  // Speicher allozieren
  len := SendMessage(hEdit, WM_GETTEXTLENGTH, 0, 0);
  GetMem(Buffer, len + 1);
  try
    ZeroMemory(Buffer, len + 1);
    // Text aus Edit holen
    SendMessage(hEdit, WM_GETTEXT, len, lParam(Buffer));
    ShowMessage(Buffer);
  finally
    FreeMem(Buffer, len + 1);
  end;
end;


////////////////////////////////////////////////////////////////////////////////
//
//  TForm1.Button1Click
//
//    OpenDialog anzeigen
//

procedure TForm1.Button1Click(Sender: TObject);
begin
  // eigene EventHandler zuweisen
  OpenDialog1.OnShow := OpenDlgOnShow;
  OpenDialog1.OnClose := OpenDlgOnClose;
  // aufrufen
  if OpenDialog1.Execute then
  begin
    ShowMessage(OpenDialog1.FileName);
  end;
end;

end.

wobei ich nicht unbedingt so viel immer kommentieren würde. Hier würde ich so gut wie gar nichts kommentieren, da eigentlich alles aus den Befehlen hervorgeht, was passiert. Ich würde wohl wirklich nur das

Delphi-Quellcode:

  // OpenDialog1.Handle ist irgendwie das falsche :?
  hParent := GetParent(OpenDialog1.Handle);

kommentieren, da das etwas komisch ist. Man bekommt irgendwie nicht das richtige Handle mit der Eigenschaft Handle von TOpenDialog. Und damit man da noch weiß, warum man das gemacht hat, wird es kommentiert. Das ist übrigens eine gute Regel: Kommentiere das Warum und nicht das Wie. Das Wie sieht man ja dann an den Befehlen.

[fkerber]

Hi!

Danke, insbesondere für den Schlusssatz, er bringt mich weiter.


Ciao Frederic

[Luckie]

Hier noch mal überarbeitet:

Delphi-Quellcode:

//////////////////////////////////////////////////////////////////////////////// 
// 
//  TForm1.OpenDlgOnShow 
// 
//    OnShowEventHandler des Dialoges 
//    Edit auf Dialog plazieren 
// 

procedure TForm1.OpenDlgOnShow(Sender: TObject); 
var 
  hParent: THandle; 
  rect: TRect; 
  hEdit: THandle; 
begin 
  // OpenDialog1.Handle ist irgendwie das falsche :? 
  hParent := GetParent(OpenDialog1.Handle); 
  GetWindowRect(hParent, rect); 
  // Dialog vergrößern für Edit 
  SetWindowPos(hParent, 0, 0, 0, rect.Right - rect.Left, rect.Bottom - rect.Top 
    + 25, SWP_NOMOVE); 
  // Edit erzeugen, ID = 101, und Fehlerbehandlung
  hEdit := CreateWindowEx(WS_EX_CLIENTEDGE, 'EDIT', '', WS_VISIBLE or WS_CHILD, 
    195, rect.Bottom - rect.Top - 27, 150, 20, hParent, 101, 0, nil); 
  if hEdit = 0 then 
    RaiseLastOSError; 
end;

Optional kann man in den Prozedur Header noch Autor, Datum, Parameter, Rückgabewert angeben. Halte ich aber für überflüssig. Bei Bedarf kann man es machen. Hier wäre es zum Beispiel überflüssig, finde ich.

Im Unit Header kann man auch noch Datum, Autor, Copyright, Erklärung was sie macht usw. dazu schreiben.

[Mamphil]

Hi!

Der Styleguide von www.delphi-source.de bieten IMHO eine gute Übersicht, wie Pascal- / Delphi-Code gut aussehen kann und enthält auch vernünftige Tipps zur Dokumentation und Kommentierung.

Mamphil

[Bernhard Geyer]

Mittels des Syntax von JavaDoc und dem Tool Time2Help kannst Du auch einfach Hilfedateien (hlp, chm, html) aus deiner Dokumentation erstellen.