Hinweise zu Abgaben / Arbeiten mit Programmcode

Work in Progress

Wenn Sie bei mir Übungsaufgaben, Haus- oder Projektarbeiten mit einem Programmieranteil abgeben, beachten Sie bitte die folgenden Hinweise.

Was abgeben?

Geben Sie den vollständigen eigenen Code ab, nicht irgendwelche Ausschnitte. Ihr Code sollte lauffähig sein, d.h. keine Syntax- oder sonstigen Fehler bei dokumentationsgerechtem Gebrauch, Jupyter-Notebooks sollten mit Kernel → Restart Kernel and Run All laufen.

Außer in völlig trivialen Fällen, in Einführung in Python oder bei Aufgaben, bei denen ich genau vorgebe, was Sie abgeben sollen (z.B. ausgefülltes Notebook) sollten Sie eine kurze README-Datei schreiben, die alle Informationen enthält, um Ihr Programm benutzen zu können (ggf. in Form von Verweisen an andere Stellen). Wenn Sie nur ein einzelnes Skript abgeben, können diese Informationen auch in einen Kommentar / Docstring am Beginn der Datei. Dazu gehört:

• ggf. detaillierte Auflistung der Abhängigkeiten bzw. verwendeten Softwarebibliotheken, am besten allerdings maschinenlesbar wie im Abschnitt unten beschrieben.
• ggf. eine kurze Beschreibung der Bedienung bzw. des Aufrufs, mit Beschreibung der erwarteten Ein- und Ausgabeformate
• wenn irgendwas in der Umgebung erwartet wird (z.B. Dateien / Ordner mit bestimmtem Namen), schreiben Sie es hier hinein
• Überblick welche Datei etc. dient wozu, sofern das nicht offensichtlich ist

Ggf. sollten Sie Testdaten (nur Eingabe, nicht von Ihrem Programm generiertes) in geringem Umfang mitgeben, sofern nicht von mir vorgegeben.

Wenn ich Testdaten vorgebe, legen Sie die Dateien genau so wie in der Vorgabe ab (nicht umbenennen oder verschieben), damit wir gleiche Testausgangsbedingungen haben,

Was nicht abgeben?

• Bibliotheken, Fremdprogramme etc., die auch mit üblichen Mechanismen (pip, Maven) einfach zu installieren sind
• Große Datenmengen nur nach Nachfrage
• Material, das nicht zu ihrem Projekt / ihrer Aufgabe gehört oder das ich schon habe (Notebooks mit meinem Material …)
• alte Versionen, erfolglose Versuche etc.

Abhängigkeiten

In der Regel dürfen Sie externe Module (nicht Teil der Standardbibliothek Ihrer Programmiersprache) verwenden. Sie sollten jedoch möglichst incl. Version dokumentieren, was Sie dort verwendet haben. Für Python gibt es einen einfachen weg, dies zu tun: Mit pip freeze > requirements.txt erzeugen Sie eine Liste aller Bibliotheken samt Version in ihrer aktuellen Python-Umgebung. Diese Liste bearbeiten Sie dann, indem Sie alles löschen, was Sie nicht direkt für Ihren Code benötigen. Das Ergebnis kann z.B. so aussehen:

 

bokeh==0.12.0
gensim==2.0.0
numpy==1.12.1
pandas==0.19.0
requests==2.16.5

 

Geben Sie die Datei mit ab. Bitte geben Sie keine mit pip freeze generierte, unbearbeitete requirements.txt ab!

Anforderungen an Ihren Code

• Ihr Programm sollte ohne Änderungen auf anderen Rechnern (z.B. bei mir) lauffähig sein:

  • Schreiben Sie keine absoluten Pfade zu irgendwelchen Dateien in den Code, sondern verwenden Sie Kommandozeilenargumente, relative Pfade (glob('corpus/*.txt'), nicht glob('/Users/Hans/Uni/Projekte/corpus/*.txt')
  • Vermeiden Sie betriebssystemspezifischen Code. Benutzen Sie am besten pathlib.Path (Path(parent, child) oder os.path.join(parent, child) statt parent + '\\' + child)
  • Dokumentieren Sie Annahmen.

• Strukturieren Sie Ihren Code:

  • Verwenden Sie Funktionen, eher viele kurze als wenige lange
  • vermeiden Sie globale Variablen
  • mischen Sie nicht Funktions-/Klassendefinitionen mit globalem Code
  • dokumentieren Sie ihre Funktionen kurz (was bedeuten Parameter? Was ist der Rückgabewert?)
  • verwenden Sie sinnvolle Defaults
  • mischen Sie nicht User-Interface (z.B. print-Ausgaben) mit Funktionalität (z.B. Algorithmen), dh das sollte in getrennte Funktionen
• Achten Sie auf lesbaren Programmcode. Halten Sie sich möglichst an etablierte Styleguides für Ihre Programmiersprache (für Python z.B. PEP8).
• Verwenden Sie sprechende Variablen- und Funktionsnamen. Schreiben Sie knappe, sinnvolle Docstrings / JavaDocs / etc.

• Erläutern Sie knifflige und nicht-offensichtliche Codestellen mit einem Kommentar. Code, der für Personen, die die Programmiersprache gut kennen, auch so verständlich ist, soll nicht kommentiert werden. Verständlicher Code ist besser als kommentierter Code.

• Vermeiden Sie überflüssige, allzu detaillierte Ausgaben auf den Bildschirm.