Variablennamen - Eindeutigkeit/Aussagekraft

[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