|
|
|
|
|
Schreib"kunst" für Programmierer, Teil I
Geschrieben von: Bernhard Spuida Im ersten von zwei Artikeln über die Kunst des Schreibens beschäftigen wir uns mit den Grundlagen guten, klaren Schreibstils. Wieso, so fragst Du Dich jetzt, ist für mich als Programmierer guter Schreibstil wichtig? Ganz einfach: die Benutzer unserer Programme wollen - ebenso wie die Leser der Artikel hier auf ASPheute - möglichst schnell Nutzen aus dem Gelesenen ziehen. Und guter Schreibstil ist nicht zuletzt auch Werbung für uns selbst. Mal ehrlich: liest sich die Dokumentation schlecht, sind wir meist auch sofort gegenüber der Software voreingenommen. Ganz zu schweigen von unserer Meinung vom Programmierer. Dabei ist gutes, verständliches Schreiben nicht schwieriger zu erreichen als unklarer Stil - wir haben meist sogar weniger Mühe dabei! Für diese Artikel wird nichts besonderes vorausgesetzt. Außer vielleicht ein wenig Ehrgeiz, besser zu werden. Und Bereitschaft, sich durch Übung weiterzuentwickeln. Das trifft auch auf mich zu. Also mit Anregungen, Ergänzungen und konstruktiver Kritik bitte an mich wenden. Ich freue mich über alles was ich von Dir, Leser, dazulernen kann. TheorieUnsere Leser benötigen genauso wie ein Compiler die Einhaltung einer spezifischen Syntax, damit unser Text richtig verstanden wird. Ebenso kann Sprache genauso wie Programmcode verwickelt oder strukturiert sein mit ähnlichen Folgen für die 'Performance' wie bei einem Programm. Im Gegensatz zu einem Compiler bildet sich ein menschlicher Leser allerdings ein Urteil über den Autor und seine Fähigkeiten. Das Verständnis von geschriebenem Text beruht auf drei deutlich unterscheidbaren Eigenschaften:
Die erste dieser Eigenschaften können wir als Autoren im Allgemeinen nicht beeinflussen. Die optische Gestaltung liegt in den Händen der Layouter und Typographen denen wir unser Werk zur Fertigstellung übergeben. Die zweite Eigenschaft werden wir hier behandeln, da es für unseren Erfolg wichtig ist, daß der Leser unseren Text liest. Mit der dritten werden wir uns ebenfalls beschäftigen, da wir ja sichergehen wollen, daß unsere Leser den Zweck unseres Textes verstehen. Die Eigenschaften zwei und drei überschneiden sich zwar teilweise, aber wir werden sie trotzdem getrennt behandeln. Um zu verdeutlichen, was konkret unter diesen drei Eigenschaften verstehen ist, betrachten wir ein Beispiel das wohl jeder kennt - Versicherungsverträge und AGBs auf der Rückseite von Lieferscheinen, die wohl notorisch unlesbarsten Dokumente.
Im zweiten Artikel werden wir uns dann mit Stilfragen beschäftigen. Schließlich muß technisches Schreiben ja nicht gleichbedeutend mit schlechtem oder zumindest uninteressantem Schreiben sein. Und jetzt auf ins Vergnügen. LesbarkeitDer Vorgang des Lesens und Verstehens ist wesentlich komplexer als der physische Vorgang des Sehens und Entzifferns von Buchstaben und Textsegmenten. Nach dieser ersten Stufe - die unter 'Leserlichkeit' fällt - kommen wir zu der Stufe auf der der gelesene Text in einzelne 'Tokens' zerlegt wird, genau so wie es ein Compiler tut. Das ist Sache der Lesbarkeit, wir müssen uns also mit den folgenden Themen beschäftigen wenn wir diesen Schritt erfolgreich überstehen wollen:
Ist ein technischer Text schwer lesbar, so wird der Leser meist annehmen daß der Code den der Autor schreibt ähnlich aussieht. Programmcode ist genauso wie unser Text in einer Sprache verfasst, es liegt also nahe von der Qualität des Textes auf die Qualität des Codes zu schließen. 1. Wohlgeformte SätzeUnter 'wohlgeformten Sätzen' sind nicht einfach grammatikalisch korrekt gebaute Sätze zu verstehen, sondern klar gebaute Sätze. Wir werden dies anhand einiger Negativbeispiele untersuchen und Lösungsmöglichkeiten vorstellen. Satz unvollständig. Das Auslassen wichtiger Satzteile ist unter allen Umständen zu vermeiden. In diesem Falle fehlen sowohl Verb als auch Partizip. Im Zweifelsfall sollte man seinen Text laut vorlesen. Derartige Fehler treten häufig in langen Schachtelsätzen auf. Falls man diese Sätze nicht aufteilen kann, sind sie besonders sorgfältig zu korrigieren. In diesem Fall, der ja einen wichtigen Punkt illustrieren soll, haben wir, wie klar ersichtlich, zu viele Kommas eingesetzt. Zeichensetzung sollte sparsam verwendet werden. Nicht überall wo es sinnvoll scheint gehört tatsächlich auch ein Komma hin. Die komplexen Regeln der Kommasetzung in der Deutschen Sprache können ohne große Verluste durch eine Handvoll Faustregeln ersetzt werden. Siehe dazu das unten angeführte Buch 'Deutsch für Profis'. Ein wichtiger Punkt bei der Kommasetzung ist der, daß Kommas keine Sprechpausen beim Lesen darstellen. Das war im frühen Mitteldeutsch so, gilt heute jedoch nicht mehr. Kommas dienen zur Trennung von Sinneinheiten. Der Aufruf zur Sparsamkeit gilt auch für alle anderen Satzzeichen. Es ließen sich natürlich noch unzählige weitere Negativbeispiele konstruieren, aber bei der täglichen Lektüre sollten uns genug davon unterkommen. Bei bewußtem Lesen lernen wir. Hier ein Negativbeispiel aus einem von mir verfassten Artikel: Voraussetzung für das bessere Verständnis des Artikels ist eine genaue Kenntnis des julianischen Kalenders in Bezug auf datumsmäßig bedingte Bräuche. Dieses (absichtlich so formulierte) Monster soll lediglich sagen, daß man diesen am 1. April veröffentlichten Artikel Debugging in der Tiefe wegen des Erscheinungsdatums nicht ernst nehmen sollte. 2. Überlange SätzeHäufig finden wir Sätze vor die zu lang sind. Unser Kurzzeitgedächtnis hat nur eine begrenzte Kapazität. Ähnlich wie Telefonnummern fünf plus/minus zwei Ziffern lang sein sollten gibt es auch Grenzen für die Satzlänge. Es lässt sich eine Regel angeben - die jedoch beileibe nicht die einzige derartige Regel darstellt - daß ein Satz nicht mehr als die erwünschte Länge von fünfzehn Worten erreichen sollte, keinesfalls unter die Grenze von sieben Worten fallen darf und niemals über die Erträglichkeitsgrenze von zwanzig Worten hinausgehen darf, obwohl sich längere Sätze durchaus in der Hochliteratur finden wo selbst Zeichensetzung, so wie sie hier zur Erleichterung des Lesevorganges eingesetzt wird, zur Erzielung neuartiger, experimenteller Effekte ausgelassen wird. Dieses Beispiel ist mit seinen 77 Worten wohl etwas länger als das was wir in unseren eigenen Werken erwarten. Liest man jedoch seine eigenen Texte, so finden sich mitunter ähnlich lange Sätze, die zum Beispiel eine Abfolge von Ereignissen und ihrer Behandlung beschreiben. Komplexe Gedankengänge profitieren von der Zerlegung in Sätze handlicher Länge. Die Versuchung einfach dahinzuschreiben ist groß. Widerstehen! Die Logik des Textes profitiert davon. Was nicht unmittelbar zum Verständnis benötigt wird, kann ausgelassen werden. 3. Kurze SätzeKurze Sätze lesen sich leicht, wirken jedoch atemlos und unnötig aufgeregt. Sätze können kurz sein. Dann lesen sie sich leichter. Und sind verständlicher. Aber sie wirken billig. Und führen zu Unruhe beim Leser. Dazu muß nicht mehr viel gesagt werden, da das Beispiel die Aussage gut illustriert. Wenn etwas wert ist, gesagt zu werden, dann ist es auch wert gut gesagt zu werden ohne die Sprache in Stücke zu reißen. Die menschliche Sprache ist keine RISC-Sprache. Allgemein sollte man die Länge der Sätze in den Grenzen variieren, die im Negativbeispiel unter Punkt 2 dargelegt wurden. Interessantes Schreiben hängt wesentlich von der gezielten Variation der Satzlängen und der Wortwahl ab - zu letzterer weiter unten mehr. 4. RekursionSätze werden oftmals zu zirkulären Fällen von Rekursion während des Lesens falls die Bezüge auf die jeweiligen Subjekte und Objekte unklar bleiben. Dies ist eine Folge der Verwendung des selben Pronomens für beide: Es ist nicht einfach zu verstehen um was es geht, wenn es völlig unklar bleibt von was wir eigentlich schreiben - inzwischen sollte es klar sein, um was es hier geht. In einem derartigen Fall ist es ratsam, bei einem Auftreten des jeweiligen Subjekts/Objekts - vorzugsweise beim ersten Auftreten - das Pronomen durch die Bezeichnung des Subjekts/Objekts zu ersetzen. Eine derartige Rekursion ist häufig ein Zeichen für Faulheit auf Seiten des Autors, da sie eine Unwilligkeit des Autors andeutet einen Gedanken sauber auszuformulieren. Dies ist jedoch nur eine kurzfristige Ersparnis, da erfahrungsgemäß Leser den Autor mit Bitte um nähere Erklärung kontaktieren und ihm somit unnötige Arbeit aufhalsen. Eine andere Form von Rekursionsfehler tritt bei unseren Lesern auf wenn wir sie mit überladenen Sätzen voller Einschübe, Ellipsen und anderer rhetorischen Techniken konfrontieren. All das benötigt Platz auf dem 'Stack' des Lesers - und dieser Stack ist nicht tief. 'Push' und 'pop' über mehr als drei Ebenen führt zur Katastrophe - für das Verständnis unseres Satzes! Der Leser, also der beabsichtigte Rezipient unseres Textes, eines hoffentlich klar und logisch aufgebauten Dokuments, wird, so er in der Lage ist unsere Prosa zu verstehen, zu einer wohlfundierten Meinung darüber gelangen, was der jeweils vorliegende Satz, so wie dieser, ihm, dem Leser, mitteilt. Der obige Satz ist grammatikalisch korrekt, wird aber wohl beim durchschnittlichen Leser einen Stacküberlauf provozieren. Derartiger verschachtelter Stil sollte wo immer möglich vermieden werden. Ebenso wie rekursiver Code können solche Sätze häufig 'ausgewalzt werden. Zerlege derartige Monster in Teile denn kürzere Sätze sind leichter lesbar. Falls dies nicht möglich ist, gehören die Teile die zusammen gehören möglichst nahe beieinander angeordnet. 5. WortwahlDer Vorgang des Lesens ist für den Leser stets anstrengend. Daher ist es unsere Aufgabe, ihm diesen Vorgang so leicht wie möglich zu machen. Eine Möglichkeit dies zu erreichen ist es, Abwechslung in unsere Wortwahl zu bringen. Verwendet man wieder und wieder die selben Worte um wieder und wieder die selben Themen zu behandeln, so wird mit jeder Wiederholung die Bereitschaft weiterzulesen geringer und geringer. Für jedes beliebige Wort steht uns mindestens ein Synonym zur Verfügung. Man sollte nicht zögern, im Zweifelsfall einen Thesaurus zu verwenden um nach alternativen Worten zu suchen. Die wiederholte Verwendung von stets gleich lautenden Wendungen sollte vermieden werden, außer man versucht künstlerische Intention zu transportieren - dies ist bei technischen Texten jedoch so gut wie nie der Fall. Und:
Niemals die gleichen eröffnenden Worte in zwei oder mehr aufeinanderfolgenden Sätzen
verwenden. Die Wiederholung ist der Todfeind jedes Interesses beim Leser.
VerständlichkeitLesen ist ein komplexer Vorgang, bei dem auf die besprochene 'Tokenisierung' das 'Parsen' folgt - das Verstehen der einzelnen Symbole und deren Beziehungen untereinander. Diese beiden Schritte lassen sich jedoch nicht sauber trennen. Ein großer Teil der Probleme mit der Verständlichkeit von Texten wurden bereits weiter oben unter dem Begriff der 'Rekursion' behandelt.
Rekursion ist der Feind der Verständlichkeit.
Ein verständliches technisches Dokument besitzt stets einen logischen Aufbau. Jeder behandelte Gegenstand baut auf dem vorhergehenden auf. Wird ein neuer Begriff zur Behandlung des anstehenden Gegenstandes benötigt, so sollte er vor der Beschäftigung mit diesem Thema eingeführt werden. Dies gilt auf jeder Ebene vom Gesamttext über Kapitel und Absätze des Textes bis hinab zu den einzelnen Sätzen. Die grundlegenden Schritte sind:
Natürlich kann für manche Themen die klassische Struktur mit 'These, Antithese, Synthese' angemessener sein, z.B. bei der Erläuterung von Designentscheidungen, doch ist meist die oben aufgeführte Abfolge genau das was wir benötigen. Auf dem 'atomaren' Niveau eines Satzes, unterhalb seines Inhaltes, wird die Logik seiner Struktur durch reine Grammatik bestimmt. Deshalb ist eine grundlegende Kenntnis grammatischer Grundlagen notwendig um unsere Gedanken so dem Leser zu vermitteln wie wir es als Autoren beabsichtigen. 1. DefinitionIn diesem Abschnitt eines Dokuments werden alle für das Verständnis des Folgenden notwendigen Begriffe und Konzepte definiert. In manchen Fällen genügt Bezugnahme auf zuvor im Dokument vorgestelltes Material. Bezugnahme auf später besprochenes Material ist zu vermeiden. Sollte es aus irgendwelchen Gründen notwendig sein, so kann man die Definitionen in Endnoten oder ein Glossar auslagern. Fußnoten sind nicht für die Aufnahme von Definitionen bestimmt. Sie dienen zur weiteren Erklärung des vorliegenden oder zur Darstellung von 'non sequiturs'. 2. Behauptung/TheoremDie Aufgabe dieses Abschnittes ist die Vorstellung des Grundgedankens oder des Konzeptes mit dem sich das Dokument oder der aktuelle Dokumentabschnitt beschäftigt. Wir sollten auf einfache Art darstellen womit wir bei unserem Argument beginnen und wohin wir es zu führen beabsichtigen. Hier ist nicht der Platz um 'Warum' oder 'Wie' darzulegen. Das 'Warum' sollte aus den vorhergehenden Abschnitten des Dokuments klar sein, während das 'Wie' Gegenstand des nächsten Abschnittes sein sollte. In Benutzerhandbüchern ist dies der Ort, an dem die zu erklärende Funktion vorgestellt wird. 3. Erläuterung/BeweisDieser Abschnitt unseres Dokuments dient dazu, die Rechtfertigung des zuvor präsentierten Gedankens zu liefern. Dieser Abschnitt kann rein argumentativ sein - um z.B. architekturale Entscheidungen zu rechtfertigen - oder sich dem Stil mathematischer Beweise annähern. Im Falle einer Programmimplementation ist dies der Ort um die Arbeitsweise Schritt für Schritt zu erklären. Handelt es sich um ein Benutzerhandbuch, sollte man hier die Programmoberfläche und die zur Durchführung spezifischer Aufgaben notwendigen Schritte erklären. 4. SchlußfolgerungUm den Erfolg eines Textes zu gewährleisten, muß eine Schlußfolgerung gezogen werden. In ihr sollten die oben genannten Schritte in Kurzform wiederholt und zusammengefasst werden. Dadurch wird der Eindruck des vorgestellten Inhaltes beim Leser nachhaltig verstärkt. Im Gegensatz zu einem Computer muß der Mensch eine Anleitung mehrfach erhalten, bevor er sich für die Durchführung entscheidet. Die Aussage eines Textes muß mehrfach wiederholt werden. Der menschliche Verstand kann sich mit 'Einmal und nie wieder' nicht anfreunden. SchlußbemerkungWie man sieht, ist gutes, interessantes Schreiben nicht schwer und nützt Allen. Dem Leser wird seine Aufgabe erleichtert, uns Autoren wird Anerkennung für unsere gute Arbeit zuteil. In Teil II dieses Artikels werden wir uns mit Stilfragen beschäftigen. Bis dahin: viel Spaß und Erfolg beim Schreiben! LiteraturWolf Schneider: Deutsch für Profis, Goldmann Verlag - Ein absolutes Muß für jeden der beruflich schreibt. Gut geschrieben, rein auf Praxis orientiert - der langjährige Chefredakteur des 'Stern' weiß wovon er schreibt. Verwandte Artikel
Debugging in der Tiefe Links zu anderen SitesWenn Sie jetzt Fragen haben...Wenn Sie Fragen rund um die in diesem Artikel vorgestellte Technologie haben, dann schauen Sie einfach bei uns in den Community Foren der deutschen .NET Community vorbei. Die Teilnehmer helfen Ihnen gerne, wenn Sie sich zur im Artikel vorgestellten Technologie weiterbilden möchten.
Haben Sie Fragen die sich direkt auf den Inhalt des Artikels beziehen, dann schreiben Sie dem Autor! Unsere Autoren freuen sich über Feedback zu ihren Artikeln. Ein einfacher Klick auf die Autor kontaktieren Schaltfläche (weiter unten) und schon haben Sie ein für diesen Artikel personalisiertes Anfrageformular.
Und zu guter Letzt möchten wir Sie bitten, den Artikel zu bewerten. Damit helfen Sie uns, die Qualität der Artikel zu verbessern - und anderen Lesern bei der Auswahl der Artikel, die sie lesen sollten.
©2000-2006 AspHeute.com |
