Variablennamen - Eindeutigkeit/Aussagekraft

[romy]

Hi,

Als ich mein beinahe fertiges Projekt mir mal so im nachgang angeschaut habe ist mir häufig aufgefallen, dass ich trotz Doku mit einigen Dingen nichts mehr anfangen kann,d.h. ich weiss nicht mehr was ich meinte.

Das finde ich ziemlich fatal und würde dies gern bei weiterführenden Projekten ändern. Dazu hätte ich gern mal ein paar Meinungen gehört.
Bei der Forumsuche nach diesem Thema habe ich irgendiwe keinen geeigneten Suchbegriff gefunden -> wenn es also schon einen Thread dazu gab, vielleicht weiss ja noch jemand wo der steht.

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.

2. Deutsch oder Englisch oder gemischt?

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

mhm, was denkt ihr
mir geht es vorallendingen um Nachvollziehbarkeit. (auch noch 6 Monate später ;))

ciao
romy

[Philipp Hasenfratz]

Halihallo romy

Bei der Forumsuche nach diesem Thema habe ich irgendiwe keinen geeigneten Suchbegriff gefunden -> wenn es also schon einen Thread dazu gab, vielleicht weiss ja noch jemand wo der steht.

Ne, leider nein.

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.

Wenn es nötig ist, dann mache ich das mit Prefixen, welche auf den Anwendungszweck
hindeuten. Z. B. lan_wort, sys_remote_user, usr_name . Aber dass du soviele Variablen
hast, lässt mich darauf schliessen, dass du riesige Programme in einer Datei hast; dann
kommt man notgedrungen in Probleme, eine sinnvolle Namensgebung zu erstellen. Meiner
Meinung nach ist es besser, wenn die Programme per se aufgesplittet werden und so in
eine Art "Namensraum" (u. B. eben Sprachmodul, Systemmodul, Datenstoragemodul
etc.) "gepresst" werden. In diesen Namensräumen oder besser Anwendungsbereichen sind
auch einfache, kurze Namen für Variablen eindeutig zu verstehen (zumindest besser).

2. Deutsch oder Englisch oder gemischt?

Wie es dir beliebt, aber im Sinne von anderen: Entscheide dich für eine Sprache.

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

Höchstens die wichtigsten und am besten dort, wo sie definiert sind: im Quelltext. Das
erleichtert anderen Programmierern, das lesen des Quelltextes (nicht bei jeder Variablen
in einer anderen Dokumentation nachsehen).

---

Allgemein: Die Funktionsweise/Zweck der Variablen lässt sich auch aus dem Kontext lesen.
Wenn der Kontext (kleine Codeschnipsel) also gut dokumentiert bzw. selbsterklärend ist,
ist auch die Variable von Sinn her "wiederherstellbar". Falls der Kontext nicht für sich
spricht bzw. nicht auf Anhieb erkenntlich ist, braucht es einen Hinweis für den Leser.
Eine ausgewogene in-file (durch Kommentare oder meinetwegen POD) Dokumentation kleiner
Codepassagen und Variablen fördert das Lesen des Quelltextes enorm und du wirst keine
Probleme damit haben, dein Code auch in 6 Mt. noch zu verstehen.

Viele Grüsse und HTH

Philipp

[romy]

Hi Philipp,

Wenn es nötig ist, dann mache ich das mit Prefixen, welche auf den Anwendungszweck
hindeuten. Z. B. lan_wort, sys_remote_user, usr_name .

daran hatte ich auch gedacht, ist wahrscheinlich am besten.

hast, lässt mich darauf schliessen, dass du riesige Programme in einer Datei hast;

es geht, grösstenteils ist es schon aufgesplittet
aber trotzdem fand ich es irgendwie unleserlich
mhm...allerdings sollte mich das wahrscheinlich zum Nachdenken anregen, es doch noch ein bisschen besser aufzusplitten...

Allgemein: Die Funktionsweise/Zweck der Variablen lässt sich auch aus dem Kontext lesen.
Wenn der Kontext (kleine Codeschnipsel) also gut dokumentiert bzw. selbsterklärend ist,
ist auch die Variable von Sinn her "wiederherstellbar". Falls der Kontext nicht für sich
spricht bzw. nicht auf Anhieb erkenntlich ist, braucht es einen Hinweis für den Leser.
Eine ausgewogene in-file (durch Kommentare oder meinetwegen POD) Dokumentation kleiner
Codepassagen und Variablen fördert das Lesen des Quelltextes enorm und du wirst keine
Probleme damit haben, dein Code auch in 6 Mt. noch zu verstehen.

mhm dass ist wahrscheinlich ein wichtiger Aspekt, ich schätze die Doku war nicht ausgereift genug. Ich habe damit so meine Schwierigkeiten, da mir mein Geschreibe in dem Moment des Schreibens immer sehr Sinnvoll erscheint, aber später ... ;)
Das liegt wohl daran, dass man direkt in der Materie steckt und Dinge selbsterklärend findet, die es gar nicht sind...

ist wahrscheinlich alles eine Frage des richtigen Systems?

ih ;)

danke
romy

[Andreas Korthaus]

Hallo!

Will an dieser Stelle nochwas in den Raum werfen, hab das mal bei einem PERL-Modul gesehen:
da wurde auch immer der Datentyp mit in den Namen aufgenommen, so z.B.
"$aUserdata" wäre ein Array, selbiges mit s für string, i für Interger...

Was haltet Ihr davon?

Grüße
Andreas

[Hans-Peter Rieger]

Hallo Andreas,

Will an dieser Stelle nochwas in den Raum werfen, hab das mal bei einem PERL-Modul gesehen:
da wurde auch immer der Datentyp mit in den Namen aufgenommen, so z.B.
"$aUserdata" wäre ein Array, selbiges mit s für string, i für Interger...

Was haltet Ihr davon?

Na ja, das entspricht der "Ungarischen Notation" (siehe mein Posting von vorhin) und ist bei vielen großen SW-Häusern Standard.

Ciao
Hans-Peter

[Tom2]

Hi

Ich kann Philipps aussagen nur bestätigen. Ich möchte dir trotzdem noch ein paar weitere Tipps geben, die mir sehr gehofen haben.

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.
   Wenn es nötig ist, dann mache ich das mit Prefixen, welche auf den Anwendungszweck hindeuten. [...]

Zusätzlich habe ich mir noch angewöhnt, einen Prefix für den Datentyp zu setzen. Wenn du Varianten (also Variablen, die mehrere Datentypen speichern können) verwendest, so ist dies sehr hilfreich.
Auch der Stil trägt IMHO sehr viel zum Verstehen bei: z.B. schreibe ich Konstanten gross und verwende in normalen Variablennamen Gross-/Kleinschreibung um die Lesbarkeit zu verbessern. Funktionsnamen   beginnen bei mir meist mit einem Verb.

2. Deutsch oder Englisch oder gemischt?
   Wie es dir beliebt, aber im Sinne von anderen: Entscheide dich für eine Sprache.

Also ich entscheide mich (zumindest bei Kommentaren) für die Muttersprache. Dadurch kann ich ganz klar niederschreiben, was ich mir beim Coden überlegt habe.

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

Ich schreibe jeweils hinter der Definition einer Variablen einen kurzen Kommentar.

Du merkst also: Kommentare, Kommentare, Kommentare. Teile dein Programm gedanklich in Schritte auf und kommentiere diese. Wie gross du diese Schritte wählst musst du selbst herausfinden. Wichtige Passagen, an denen du lange gearbeitet hast oder bei der dir viele Fehler unterlaufen sind, solltest du sehr ausführlich dokumentieren. Und eigne dir einen gewissen Programmierstil an und behalte diesen bei. Dadurch wird das Lesen eines Programms auch stark vereinfacht.

MfG

Tom2

PS: Hey, dies ist ja mein erstes Posting im Jahre 2003! Somit wünsche ich allen noch nachträglich ein gutes Neues!

[Eidgenosse]

Hallo Romy,

ich nehme meist deutsche Variablennamen, da man da am wenigsten in Konflikt mit dem (englischen) Befehlssatz gerät.

Gruß

Eidgenosse

[Andreas Korthaus]

Hallo!

ich nehme meist deutsche Variablennamen, da man da am wenigsten in Konflikt mit dem (englischen) Befehlssatz gerät.

Das Probiere ich eigentlich auch, nur sind englische Wörter meist kürzer und enthalten keien Sonderzeuchne, daher habe ich am Ende auch immer os eine Mischung => nicht gut.

Grüße
Andreas

[Cheatah]

Hi,

Als ich mein beinahe fertiges Projekt mir mal so im nachgang angeschaut habe ist mir häufig aufgefallen, dass ich trotz Doku mit einigen Dingen nichts mehr anfangen kann,d.h. ich weiss nicht mehr was ich meinte.

willkommen im Club :-)

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.

Sprechende Namen. Die meisten Style-Dokus empfehlen, die Schreibweise an sich mit einer gewissen Semantik zu versehen: $durch_unterstrich_getrennt für "normale" Variablen, $mitGrossBuchstaben für systemnahe Variablen (das eigene System ist gemeint), $KOMPLETT_GROSS für Konstanten und global vordefinierte Variablen. Vor allen Dingen sollte man beim Lesen des Variablennamen wissen, was sie enthält.

2. Deutsch oder Englisch oder gemischt?

Deutsch oder Englisch. _Niemals_ gemischt. Im Hinblick auf Internationalität empfehle ich Englisch - es sollte nicht nötig sein, den Code an sich übersetzen zu müssen.

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

Never underestimate the power of incode documentation. Wenn eine Variable über den Namen hinaus noch eine Beschreibung benötigt, tue es zumindest dort, wo Du die Variable setzt; bei öffentlichen Variablen (in Objekten und Schnittstellen etwa) oder bei solchen, denen eine sehr besondere Bedeutung zukommt, lohnt sich eine Dokumentation zu Beginn des Codes. Eine Dokumentation _außerhalb_ des Codes sollte nur die Anwendung desselben beschreiben.

Bedenke insbesondere auch, dass Variablen nicht alles sind. Bei einem guten Programmkonzept sind die meisten Variablen nur lokal von Bedeutung; sie werden anderen Funktionen oder Objekten übergeben. Dort kann die Bedeutung dann gerne eine andere sein, und der Name ergo ebenfalls - ein Objekt, eine Klasse, eine Funktion usw. sollte immer auch separat verstanden werden können, nicht nur in Abhängigkeit von anderen. Setze Dich also beim Namen nicht fest, in der Art "sie muss aber hier $x heißen, weil sie dort auch $x heißt". Der Name muss im jeweiligen Kontext klar verstanden werden können.

Für die Namen der Klassen, Objekte, Methoden, Funktionen, Module, Wasimmer gilt natürlich analoges. Wer in Python etwas versiert ist, wird diese Vorstellung leicht adaptieren können... diese Sprache sieht _alles_ als Variable an, was einen Namen hat :-)

mir geht es vorallendingen um Nachvollziehbarkeit. (auch noch 6 Monate später ;))

Meine Güte, Du denkst aber in verdammt großen Bahnen *g* Einen guten Code erkennt man daran, dass man ihn auch nach sechs _Wochen_ noch versteht...

Cheatah

[Sönke Tesch]

Als ich mein beinahe fertiges Projekt mir mal so im nachgang angeschaut habe ist mir häufig aufgefallen, dass ich trotz Doku mit einigen Dingen nichts mehr anfangen kann,d.h. ich weiss nicht mehr was ich meinte.

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.

Zwei Grundregeln:

• Allgemeine, kurzlebige Geschichten haben nur sehr kurze Namen, zum Beispiel i und j für numerische Zähler, c für einen Buchstaben.

• Alle anderen Namen sollten beschreibend sein, aber auch nicht so ellenlang, daß man schon bei der zweiten Benutzung einen Schreibkrampf kriegt.

• Zusammengehörige Variablen werden in ein einziges Objekt verpackt, d.h. sie spuken nicht als einzelne Variablen durch die Gegend à la kunde_vorname und kunde_nachname, sondern als kunde.vorname und kunde.nachname oder kunde["vorname"] und kunde["nachname"] (struct, record, assoziative Felder, je nachdem, was die Sprache bietet).

Mehr braucht's in Bezug auf Variablen IMHO nicht.

2. Deutsch oder Englisch oder gemischt?

Das ist reine Geschmackssache. Mir fällt allerdings öfters auf, daß englische Bezeichnungen einfacher, weil kürzer und besser strukturierbar (wenn sie aus mehreren Komponenten bestehen) sind - oder zumindest zu sein scheinen..

Aber solange man nicht -wie auch es auch hier im Forum ab und an nett zu sehen ist- in Denglisch verfällt, ist das wohl ziemlich wurst ;)

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

Nein, die drei Regeln oben reichen mir. Ein extra Beschreibungsblock würde den Code vielleicht sogar noch unübersichtlicher machen, weil er gewissermaßen im Weg steht.

mir geht es vorallendingen um Nachvollziehbarkeit. (auch noch 6

Nachvollziehbarkeit beruht meiner Meinung nach nur zu einem sehr kleinen Teil auf Variablennamen; der Großteil eines Programm besteht schließlich nicht aus Variablen, sondern aus Code - und diesen gilt es zu kommentieren.
Sicher ist es äußerst hilfreich, wenn eine Variable einen beschreibenden, einprägsamen Namen hat, aber einerseits hast Du in einem Variablennamen selten soviel Platz, die volle Funktion zu beschreiben, und zum anderen ergibt sich die volle Funktion einer Variablen normalerweise nur in Zusammenhang mit dem Code, der um sie herum steht. Um eine Codekommentierung kommt man also nicht herum, und mit dieser Codekommentierung werden automatisch auch die Variablen beschrieben.

Gruß,
  soenk.e

[Jan]

Hi,
ich empfehle da 'Code Complete' von Steve McConnell[1] als Lektuere. Es beantwortet auch Fragen die Du dir erst spaeter stellen wirst schon.

Generell kann man sagen, das Konsistenz sehr Wichtig ist. Sowohl Kommentare als auch Variablen und Funktionsnamen sollten durchgehend einsprachig gehalten sein.

Es gibt Programme, die dir aus deinem Quellcode und den darin enthalten Kommentaren, automatisch eine API-Referenz erstellen (javadoc, PHPDoc).

Jan
--
[1] http://www.amazon.de/exec/obidos/ASIN/1556154844/qid=1041933431/sr=2-1/ref=sr_aps_prod_1_1/028-5867046-9558145

[Michael Schröpl]

Hi romy,

Als ich mein beinahe fertiges Projekt mir mal so im nachgang angeschaut habe ist mir häufig aufgefallen, dass ich trotz Doku mit einigen Dingen nichts mehr anfangen kann,d.h. ich weiss nicht mehr was ich meinte.

das ist eine wichtige Erfahrung, die jeder Programmierer einmal gemacht haben muß. (Je früher, desto besser. ;-)

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.

Entwickele Deinen eigenen Stil - und halte Dich daran.

Deine Konventionen werden so einfach sein, daß sie sich in einer einstelligen Anzahl von Regeln beschreiben lassen; es schadet nichts, wenn Du diese Regeln schriftlich festhältst (sogar in der Programmdokumentation, wenn das Projekt groß genug ist). Deine Kollegen, die Deinen Quelltext eines Tages lesen und verstehen (womöglich sogar ändern) müssen, werden es Dir danken.

2. Deutsch oder Englisch oder gemischt?

Da bin ich nicht sonderlich puristisch - wenn der Name sprechend ist, dann halte ich die Sprache für weniger wichtig.
Ich bin ja auch nicht der Meinung, daß man unbedingt alle englischen IT-Fachbegriffe eindeutschen müsse ...

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

Das kommt darauf an ...

Ich habe typischerweise Programmabschnitte mit globalen Variablen, und dort dokumentiere ich deren Bedeutung sehr genau - weil diese eben nicht aus der impliziten Verwendung der Variablen (die an ganz anderen Stellen erfolgt) klar wird.
Bei lokalen Variablen dokumentiere ich eher die Statements, welche diese Variablen benutzen (ein 1:1-Verhältnis der Zeilen zwischen natürlicher und Programmiersprache ist gar nicht selten - manche Statements, die entsprechende Design-Entscheidungen implementieren, sind auch mal 5 oder 10 Zeilen wert, und semantisch bzw. performancemäßig gescheiterte Implementierungsversuche lasse ich oftmals in auskommentierter Form und mit entsprechenden Anmerkungen im Quelltext drin stehen) ... da muß dann ein sprechender Name für die Variable selbstdokumentierend genug sein.

mhm, was denkt ihr

Die Hauptsache ist für mich, zu dokumentieren,
 a) was das Programm tun soll (und was es bewußt nicht tun kann) und
 b) wie es das ungefähr tut, d. h. insbesondere, welche Programmteile für welche Funktionen zuständig sind und wie die APIs zwischen ihnen funktionieren.
Jede einzelne Funktion ist mir in dieser Hinsicht ein paar Zeilen Anmerkungen wert. Wenn der Rote Faden gut dokumentiert ist, dann finde ich mich in den Details schnell wieder zurecht; programmiertechnische Tricks sind natürlich zusätzliche Kommentare wert.

Ansonsten ist es eine Frage des Programmierstils, wie man Programme liest und schreibt. Mein erstes Gebot dabei ist: Programmquelltexte werden nur einmal geschrieben, aber beliebig oft gelesen - also dokumentiere ich sie _heftig_. Ein Verhältnis von 60% Kommentarzeilen zu 40% Programmcode-Zeilen ist für mich völlig normal.

Es ist sogar so, daß ich beim Programmieren inzwischen fast immer zuerst den Kommentar schreibe und erst danach die konkrete Ausprägung in der entsprechenden Programmiersprache - schon bei meinen ersten Versuchen will ich die Programmlogik in einer Art und Weise beschrieben haben, daß ich selbst mir eventueller Denkfehler bewußt werde. Und der Kollege, der mir gerade mal über die Schulter sieht, ebenfalls - es kommt oft vor, daß der einen Fehler sieht, den ich nicht bemerken würde, weil man als Programmierer an seine eigenen Denkfehler einfach glaubt, während für einen Zuschauer alle Ideen eines fremden Programms erst mal neu sind und alle dasselbe Mißtrauen rechtfertigen.

mir geht es vorallendingen um Nachvollziehbarkeit. (auch noch 6 Monate später ;))

Ich besitze Quelltexte aus dem Jahre 1985 von einem Programm, das weltweit von etwa 100 Leuten verwendet wird und in dem ich noch heute ab und zu kleine Änderungen vornehme (beispielsweise habe ich Ende der 90er Jahre die gesamte Ausgabe von whitespace-formatiertem ASCII auf HTML umgestellt). Und das Ding umfaßt derzeit etwa 33.000 Zeilen Quelltext plus Konfigurationsdateien (das mehrsprachige Meldungssystem ist ausgelagert), in denen ich mich zurecht finden muß, wenn ein Anwender (beispielsweise ich selbst) ein Problem damit hat.
Ein solches Projekt, wo der Quelltext nach knapp zwei Jahrzehnten (und mehreren Portierungen auf neue Plattformen: Ursprünglich ein Apple II+-kompatibler Nachbau, später Atari ST, seit einem Jahrzehnt dann M$-DOS) noch im Einsatz ist (und ich selbst mit diesem Programm seit 16 Jahren regelmäßig alle 3-4 Wochen ein Wochenende lang arbeite und dadurch Teile meiner Homepage erzeuge), schult die Disziplin beim Dokumentieren ungeheuer ...

Viele Grüße
      Michael

[Sven Rautenberg]

Moin!

mir geht es vorallendingen um Nachvollziehbarkeit. (auch noch 6 Monate später ;))

Was die anderen schon geschrieben haben: Kommentare schreiben!

Ich gehe beim Programmieren häufig so vor, dass ich ein komplexeres Problemchen erstmal ausschließlich in Kommentaren "löse", also im Prinzip in noch nicht weiter ausgeführtem Pseudocode. Ich kommentiere also als ersten Schritt, was ich tun will. Beispiel (jetzt spontan ausgedacht)

if ( // Serverstand älter als last-modified )
{
  // 304-Header ausgeben
}
else
{
  // Dokument neu generieren
}

Dieses Gerüst ist der grobe Programmablauf. Natürlich wird die eine oder andere Aufgabe beim Ausprogrammieren komplexer. Aber der Kommentar ist schon da und sagt, was gemacht wird. Außerdem habe ich mich dann gedanklich schon mit dem _gesamten_ Problem beschäftigt, widme mich also in der Folge nur noch Unterproblemen, die als Teilaufgabe eingefüllt werden müssen.

Im Beispiel (durchaus der Praxis entlehnt) ist "Dokument neu generieren" komplexer, "304-Header ausgeben" ganz simpel, und "Serverstand älter als last-modified" hängt von den Umständen ab. Ich belaste mich aber noch nicht mit Detailkrams, z.B. wie ich denn das Datum des Serverstandes feststelle (dazu gehört, welche Daten da denn alles mit reinfliessen müssen), sondern produziere erstmal die grobe Linie.

Und als Ergebnis dieser Überlegung kommt dann z.B. sowas raus, wie es auf der Homepage meiner Firma realisiert wurde:

---schnipp---

Wenn der Browser ein Conditional-GET gesendet hat und die Seite seitdem nicht geändert wurde

if (
     isset($_SERVER["HTTP_IF_MODIFIED_SINCE"])
     &&
     (
       (
         strtotime($_SERVER["HTTP_IF_MODIFIED_SINCE"]) >= filemtime($_SERVER['DOCUMENT_ROOT'].$_SERVER["SCRIPT_NAME"])
       )
       ||
       (
         strtotime($_SERVER["HTTP_IF_MODIFIED_SINCE"]) >= filemtime($_SERVER['DOCUMENT_ROOT']."index.php")
       )
       ||
       (
         strtotime($_SERVER["HTTP_IF_MODIFIED_SINCE"]) >= filemtime($_SERVER['DOCUMENT_ROOT']."news/newsteaser.html")
       )

)
   )
{
  # Status 304 ausgeben und Script beenden
  {
    header("HTTP/1.0 304 Not Modified");
    exit;
  }
}

header("Last-Modified: " . gmdate("D, d M Y H:i:s", filemtime($_SERVER['DOCUMENT_ROOT'].$urlstring)) . " GMT");
header("Expires: " . gmdate("D, d M Y H:i:s", (time()+86400) ) . " GMT"); // Expires: 1 Tag von heute an.
---schnapp---

- Sven Rautenberg

[Hans-Peter Rieger]

Hi romy,

Als ich mein beinahe fertiges Projekt mir mal so im nachgang angeschaut habe ist mir häufig aufgefallen, dass ich trotz Doku mit einigen Dingen nichts mehr anfangen kann,d.h. ich weiss nicht mehr was ich meinte.

Das könnte ein Problem der Dokumentation sein, nicht unbedingt ausschließlich der Variablen-Namen.

Das finde ich ziemlich fatal und würde dies gern bei weiterführenden Projekten ändern.

Aha: "Lessens Learned". So macht man das auch. Und zwar immer wieder. Nach jedem Projekt.

1. Wie würdet ihr die Variablen benennen, vorallendingen im Hinblick auf unterschiedliche Verwendungszwecke wie zB. Sprachvariablen, Systemvariablen, allgemeine Variablen usw.

Zuerst ein Allgemeinplatz: Mit einer eindeutigen Systemmatik (nicht nur für Variable, auch fur Funktionen, Objekte, Methoden, Prozeduren, Schnittstellen, Konstanten, Enums, blabla...). Google doch mal nach dem Begriff "Ungarische Notation". Das ist _eine_ Systematik von vielen. Vielleicht nicht die allerbeste, vielleicht sehr umstritten, aber ein gutes Beispiel, wie eine Systematik aussehen könnte, die man an seine eigene Bedürfnisse, eigenen Belange (und womöglich sogar an einer Produkt- / Abteilungs- / Firmen-weiten Coding Guideline / Programmierrichtlinie) anpassen kann.

2. Deutsch oder Englisch oder gemischt?

Englisch. Weil englisch hipp ist ? Nein, weil die englischen Begriffe im Vergleich zu den deutschen (ohne Informationsverlust) oft kürzer sind, erfahrungsgemäß besser passen (GetUserData(), SetUserData() ...) und man nicht in die Verlegenheiten von Umlauten kommen kann.

3. würdet ihr diese Variablen nochmals irgendwo auflisten um sie zu erläutern

Ja, klar. In der zugehörigen Modul- oder Interface-Beschreibung im Data Dictionary - Abhängig von Deiner Entwurfs- und Design-Methodik. Aber Variablen-Namen ist einer von vielen Punkten, die man bei so einem Projekt beachten sollte.

Ciao
Hans-Peter

[romy]

Hallo,

vielen Dank an Euch alle[1], ich denke ich hab das Grundprinzip verstanden und muss jetzt praktisch nur noch an einem eigenen System arbeiten.
Hätte da aber trotzdem noch eine Anfrage

Ich hab im PHP-Magazin (wie findet ihr eigentlich solche Zeitungen, denkt ihr es ist das Geld Wert oder würdet ihr vergleichbare Infos lieber aus dem Internet versuchen zu ziehen/beziehen) gelesen, dass es pHPDoc gibt zu Strukturierung und Erstellung von Dokumentation.
Kennt das jemand, benutzt das jemand, welcher direkte Sinn steckt dahinter, kann mir nicht so ganz vorstellen, wie das Programm wissen will, was ich wann wie kommentieren will!?

Gibt es vergleichbare Möglichkeiten?

ciao
romy

PS: [1] Da hat ja meine gesamte Whitelist geantwortet, da bin ich ja wie ein bisschen stolz *jauchzer* ;)))))

[Götz]

Hallo romy!

Kennt das jemand, benutzt das jemand, welcher direkte Sinn steckt dahinter, kann mir nicht so ganz vorstellen, wie das Programm wissen will, was ich wann wie kommentieren will!?

"Kennen" ist übertrieben, ich habs mir mal ein wenig angeschaut, doch da ich leider eh kaum kommentiere (muß ich mir unbedingt angewöhnen ;) hab ichs nie ausprobiert.

Aber soweit ich es verstanden habe (bitte korrigiert mich wenn ich falsch liege) parst PHPDoc (http://phpdoc.de) die PHP-Dateien, die es Dokumentieren soll und wertet dann die Kommentare aus.
Damit das funktioniert muß man sich natürlich auch die "Doc-Comments" zur Dokumentation angewöhnen.

PHPDoc weiß also an sich gar nix, sondern wertet "nur" die von Dir geschriebenen Kommentare aus.

Grad hab ich folgendes über PHPDoc gelesen:
PHPDoc does not have a real parser, it simply greps the informations out of the given files.
Damit ist ja die Arbeitsweise eigentlich shcon grob beschrieben ;)

MfG
Götz