Themen

Arten von Dokumentation im Code

Argumente für und gegen Kommentare

Regeln für Kommentare

Werkzeuge zur automatischen Erzeugung

Folien

PDF

Glossar

PDF

• Dokumentation im Code sollte auf das
  notwendige Minimum beschränkt werden.
• Veraltete Dokumentation schadet mehr als sie nützt.
• Formulierungen sollten so knapp und präzise wie möglich,
  die Formatierung konsistent und übersichtlich sein.
• Unklarer Code sollte nicht dokumentiert,
  sondern umgeschrieben werden.
• Dokumentationswerkzeuge erleichtern die Arbeit,
  setzen aber konsistente Formatierung voraus.

Diese Fragen dienen der persönlichen Beschäftigung mit der Thematik, werden aber nicht separat in der Vorlesung besprochen.

• Was ist das intrinsische Problem jeglicher Dokumentation? Welche Konsequenz sollte man daraus ziehen?
• Welche Arten von Kommentaren haben grundsätzlich eine Daseinsberechtigung?
• Nennen Sie allgemeine Regeln für Kommentare im Quellcode, unabhängig von der verwendeten Programmiersprache und dem Programmierparadigma.
• Welche Anforderungen hinsichtlich Formulierung und Sprache lassen sich an Kommentare im Quellcode sinnvollerweise stellen?
• Welche Vorteile bieten Werkzeuge zur automatischen Erzeugung von Dokumentation aus dem Code heraus? Welche Voraussetzungen haben sie?

Der Begriff „Real Programmers“ geht zurück auf den Artikel „Real Programmers Don't Use Pascal“ von Ed Post, ursprünglich publiziert als ein „Letter to the editor“ in Datamation, July 1983, pp. 263–265. Er greift den Titel eines Buches aus dem Vorjahr („Real Men Don't Eat Quiche“) auf, das männliche Stereotypen thematisierte und das durch den Artikel von Ed Post parodiert wird.

Weitere Details finden sich in der englischsprachigen Wikipedia.

Der Artikel selbst findet sich in unterschiedlichen Formatierungen an einigen Stellen im Internet, zumal er sehr weite Verbreitung fand:

• Reine Textfassung
  http://web.mit.edu/humor/Computers/real.programmers
• PDF-Fassung
  http://www.usm.uni-muenchen.de/~hoffmann/roff/tmp/rpdup.pdf

Auch wenn der Text eindeutig eine Parodie ist, greift er doch viele Dinge auf, die so tatsächlich in der Frühzeit der IT passierten.

Randall Munroe greift in seinem Web-Comic „xkcd“ dieses Mem auf:

• https://xkcd.com/378/

Man beachte hier besonders (wie bei jedem xkcd-Comic) den zusätzlichen Text, der als „Tooltip“ erscheint, wenn man den Mauszeiger über das Bild bewegt…

Eine kommentierte und handverlesene Liste mit weiterführender Literatur zum Thema. Die Auswahl ist zwangsläufig subjektiv.

Robert Martin widmet in seinem Buch „Clean Code“ ein ganzes Kapitel (Kapitel 4) dem Thema [Martin, 2008Martin, Robert C. (2008): Clean Code. A Handbook of Agile Software Craftmanship, Prentice Hall, Upper Saddle River, New Jersey]. Viele der Grundlagen sind allerdings wesentlich älter. Ein in mancher Hinsicht zeitloser Klassiker, der leider (momentan) nur antiquarisch erhältlich ist, ist „The Elements of Programming Style“ von Kernighan und Plaugher [Kernighan, 1978Kernighan, Brian W.; Plauger, P. J. (1978): The Elements of Programming Style, McGraw-Hill, New York]. Das dortige sechste Kapitel widmet sich dem hier diskutierten Thema. Sehr kurz und teilweise von den gleichen Autoren ist Kapitel 1 in [Kernighan, 1999Kernighan, Brian W.; Pike, Rob (1999): The Practice of Programming, Addison Wesley, Boston]. Gute Hinweise finden sich schließlich auch in [Hunt, 1999Hunt, Andrew; Thomas, David (1999): The Pragmatic Programmer, Addison-Wesley, Boston], Kapitel 8, S. 248ff.

Ein sehr gutes Buch zum Stil im Englischen ist „The Elements of Style“ von Strunk und White [Strunk, 2000Strunk, William, Jr.; White, E. B. (2000): The Elements of Style, Longman, New York]. Dieser Klassiker liefert Hinweise zu grundsätzlich gutem Stil bzgl. der Sprache. Die Python-Entwicklergemeinde bezieht sich explizit darauf, wenn es um die Kommentare geht (vgl. PEP 8 und PEP 257).

• Hunt, Andrew; Thomas, David (1999): The Pragmatic Programmer, Addison-Wesley, Boston
• Kernighan, Brian W.; Plauger, P. J. (1978): The Elements of Programming Style, McGraw-Hill, New York
• Kernighan, Brian W.; Pike, Rob (1999): The Practice of Programming, Addison Wesley, Boston
• Martin, Robert C. (2008): Clean Code. A Handbook of Agile Software Craftmanship, Prentice Hall, Upper Saddle River, New Jersey
• Strunk, William, Jr.; White, E. B. (2000): The Elements of Style, Longman, New York

Es gibt für unterschiedliche Programmiersprachen jeweils eigene Werkzeuge. Spezifisch für Python-Code sei hier auf Sphinx verwiesen. Dieses Werkzeug nutzt MarkDown oder reStructuredText (zu bevorzugen) und kann sowohl die DocStrings aus Python-Code extrahieren als auch für die Erstellung einer Nutzerdokumentation verwendet werden. Es hat sich in der Praxis bewährt und wird für sehr viele Python-Projekte verwendet.