AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren

Wie dokumentiere ich richtig?

Ein Thema von fkerber · begonnen am 7. Sep 2004 · letzter Beitrag vom 8. Sep 2004
Antwort Antwort
Seite 1 von 2  1 2   
Benutzerbild von fkerber
fkerber
(CodeLib-Manager)

Registriert seit: 9. Jul 2003
Ort: Ensdorf
6.723 Beiträge
 
Delphi XE Professional
 
#1

Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 18:57
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
Frederic Kerber
  Mit Zitat antworten Zitat
HW764
(Gast)

n/a Beiträge
 
#2

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 19:37
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.
  Mit Zitat antworten Zitat
Benutzerbild von fkerber
fkerber
(CodeLib-Manager)

Registriert seit: 9. Jul 2003
Ort: Ensdorf
6.723 Beiträge
 
Delphi XE Professional
 
#3

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 19:39
Hi!

Danke für deinen Beitrag.


Ciao Frederic
Frederic Kerber
  Mit Zitat antworten Zitat
HW764
(Gast)

n/a Beiträge
 
#4

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 19:45
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!
  Mit Zitat antworten Zitat
Benutzerbild von fkerber
fkerber
(CodeLib-Manager)

Registriert seit: 9. Jul 2003
Ort: Ensdorf
6.723 Beiträge
 
Delphi XE Professional
 
#5

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 19:52
Hi!

Danke auch für dein Beispiel.

Ciao Frederic
Frederic Kerber
  Mit Zitat antworten Zitat
Benutzerbild von Luckie
Luckie

Registriert seit: 29. Mai 2002
37.621 Beiträge
 
Delphi 2006 Professional
 
#6

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 20:04
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.
Michael
Ein Teil meines Codes würde euch verunsichern.
  Mit Zitat antworten Zitat
Benutzerbild von fkerber
fkerber
(CodeLib-Manager)

Registriert seit: 9. Jul 2003
Ort: Ensdorf
6.723 Beiträge
 
Delphi XE Professional
 
#7

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 20:08
Hi!

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


Ciao Frederic
Frederic Kerber
  Mit Zitat antworten Zitat
Benutzerbild von Luckie
Luckie

Registriert seit: 29. Mai 2002
37.621 Beiträge
 
Delphi 2006 Professional
 
#8

Re: Wie dokumentiere ich richtig?

  Alt 7. Sep 2004, 20:12
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.
Michael
Ein Teil meines Codes würde euch verunsichern.
  Mit Zitat antworten Zitat
Benutzerbild von Mamphil
Mamphil

Registriert seit: 17. Jul 2004
Ort: Garching b. München
149 Beiträge
 
Delphi 7 Professional
 
#9

Re: Wie dokumentiere ich richtig?

  Alt 8. Sep 2004, 12:10
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
  Mit Zitat antworten Zitat
Benutzerbild von Bernhard Geyer
Bernhard Geyer

Registriert seit: 13. Aug 2002
17.177 Beiträge
 
Delphi 10.4 Sydney
 
#10

Re: Wie dokumentiere ich richtig?

  Alt 8. Sep 2004, 12:15
Mittels des Syntax von JavaDoc und dem Tool Time2Help kannst Du auch einfach Hilfedateien (hlp, chm, html) aus deiner Dokumentation erstellen.
Windows Vista - Eine neue Erfahrung in Fehlern.
  Mit Zitat antworten Zitat
Antwort Antwort
Seite 1 von 2  1 2   

Themen-Optionen Thema durchsuchen
Thema durchsuchen:

Erweiterte Suche
Ansicht

Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 15:49 Uhr.
Powered by vBulletin® Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz