Headerdoku in Modulen

[Kaukasus]

Guten morgen,

also ich möchte anfangen die include Datein mit einem Header zu beschreiben, da das ja guter Programmierstil ist.

Was genau muss da im Kopf erscheinen?

Ich habe gerade schon mal angefangen. Und zwar arbeite ich an einer Datei, die html outputs, z.B. Funktionen beinhaltet, die unter anderem die <option value="">text</option> ausgeben soll.

Man schreibt doch nun in den Header Kopf auch die Prototypen der Funktionen, damit man beim Öffnen des Modul gleich sieht was es beinhaltet und was an die Funktionen übergeben werden muss, bzw.was diese zurückgeben.

Soweit bin ich:

<?php

Modulname: html output Functions

Author: B W

Last modified: Friday, July 11, 2003

---------------------------------------------------------------------------------

Prototypes:

#  -> Function prints options of a form
#  void function printOptions(array $value[], $text[])

Für die Options Funktion könnte man doch 2 arrays übergeben,oder?
Oder geht das eleganter?

Ich habe gehört, es gibt für pph so eine Library mit vorgefertigten Modulen. Wo bekommt man die her? Gibt es dazu auch eine ausführliche Doku?

Danke

[Christian Seiler]

Hallo Kaukasus,

Was genau muss da im Kopf erscheinen?

Das, was Du oder jemand anderes braucht, um sofort ersehen zu können, wozu die Datei dient. Dein Ansatz weiter unten ist meiner Ansicht nach schon recht gut.

<?php

Modulname: html output Functions

Author: B W

Last modified: Friday, July 11, 2003

Ich würde hier noch zwei Dinge anfügen: Einmal, _wer_ die Datei zuletzt modifizert hat sowie eine Versionsnummer nur für diese Datei. (so eine Art Seriennummer, die Du hochzählst oder so) Dabei würde ich eventuell noch über ein Versionsverwaltungssystem wie z.B. CVS nachdenken. Eventuell wäre im Kopf auch eine kurze Liste an Veränderungen angebracht, z.B. so:

1.2.2003, Version 1.45, Kaukasus

#     error handling introduced in the printOptions function

31.1.2003, Version 1.44, Kaukasus

#     function printOptions created

Prototypes:

#  -> Function prints options of a form
#  void function printOptions(array $value[], $text[])

Ich würde das nicht unbedingt im Header erwähnen, sondern direkt vor der Funktion:

<?php

Header ...

void printOptions (array $options)

Description:

#    prints out option Elements in the Form <option value="...">...</option>

Parameters:

#    the options that are to be printed in an associative array:
#    array ($value1 => $text1, $value2 => $text2, ...)

Return value:

#    none

Behaviour if error occurs:

#    if the first parameter is not an array, the function will do nothing

function printOptions ($options) {
  ...
}

void ...

Description:

.......

function ... (...) {
}

Für die Options Funktion könnte man doch 2 arrays übergeben,oder?

Ich würde ein assoziatives Array übergeben, wie im Beispiel oben. Du kannst dieses Array dann einfach mit foreach durchlaufen. Somit musst Du Dich nicht darum kümmern, ob die Arrays genauso lang sind. Außerdem kannst Du auch ein normales Array direkt übergeben und die Optionen werden automatisch durchnummeriert. (Da die Schlüssel eines normalen Arrays ja die Indizes sind)

Ich habe gehört, es gibt für pph so eine Library mit vorgefertigten Modulen. Wo bekommt man die her? Gibt es dazu auch eine ausführliche Doku?

Meinst Du vielleicht PEAR? (http://pear.php.net/)

Viele Grüße,
Christian