Wie dokumentiere ich richtig?

[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.