Einleitender Kommentar in einem Skript

[pixewakb]

Ich habe nach Weigend ⁴2010 (Objektorientierte Programmierung mit Python 3...) gelernt. Weigend empfiehlt auf Seite 71 als guten Programmierstiel zu Beginn des Skriptes folgenden Block:

Code: Alles auswählen

# ------------------------------------------------------
# Dateiname: quader.py
# Version: 1.0
# Funktion: Berechnung des Volumens eines Quaders
# Autor: Michael Weigend
# Datum der letzte Änderung: 26.09.09
# ------------------------------------------------------

Bei mir steht ein größeres Refactoring an, in dessen Rahmen ich momentan alle Python Skripte erfasse und dann überarbeiten möchte.

Ich habe andererseits eine Datei wie __version__.py bei dem Projekt requests gefunden und möchte mal fragen, was ihr empfehlen würdet. Ich tendiere momentan zu der Lösung mit __version__.py, einfach, weil es professioneller zu sein scheint und es mir hoffentlich bei einem package die Arbeit abnimmt, bei einer Versionsänderung die Meta-Informationen aller zig Datei-Skripte anzupassen.

Ich habe mal nach __version__.py im Netz gesucht und bin mal die PEPs durchgegangen, konnte aber keine für mich nützliche Information zu dieser Frage finden (oder ich stellte mich zu blöde an).

[__deets__]

Halte ich fuer ziemlichen Unfug. Aber der Reihe nach:

- Dateiname. Wozu ist das gut? Bestenfalls steht da der Name der Datei. Schlimmstenfalls steht da der Name, den die Datei mal hatte, bevor sie jemand aus guten Gruenden (oder wegen der Mondphase) umbenannt hat. DRY. Weglassen.
- version? Nach welchen Kriterien wird die vergeben, erhoeht, hat sie nur major, marjo/minor, major/minor/revision? Und wenn man auch nur *milde* kompliziertere Sachen macht, und brav modularisiert, und dann ein neues feature baut, das aber nur eines der Module betrifft - ist das dann nur da zu inkrementieren, oder ueberall gleich, oder wie? Code gehoert in ein Versionskontrollsystem. Jedes, das es wert ist, verwandt zu werden, beherrscht tagging oder aehnliches. Eine Version gehoert also als tag oder bestenfalls als Eintrag in ein Changelog. Und last but not least ist dieser Eintrag *ohne* Versionskontrollsystem eh voelliger Unfug, denn ohne klaren Weg, wie man an eine alte Version kommt, ist es halt "aktuelle Version".
- Funktion: allgemeiner Kommentar ueber die Funktion des Moduls/Skripts. Kann man machen, ja.
- Autor: Kann man auch machen, wenn man auf Copyright-Gehummse steht. Ist aber in Versionskontrolle enthalten.
- Datum der letzten Aenderung: komplett analog zum Kommentar zu version.

Also alles in allem ziemlich viel Cargocultiges das irgendwie den Eindruck von "professionell programmiert" erwecken soll, ohne viel dahinter.

[MagBen]

Ist aber in Versionskontrolle enthalten.

Das Tag @Author sagt nur wer die letzte Änderung gemacht hat, nicht von wem der Code hauptsächlich stammt.

Soll das Ganze mit Doxygen zu einer schönen HTML-Doku umgewandelt werden, dann würde ich das ganze so schreiben:

Code: Alles auswählen

"""!
Berechnung des Volumens eines Quaders.
"""

also ohne die #-Kommentarzeichen.
Wobei das Modul höchstwahrscheinlich ja eben nicht das Volumen berechnet, sondern eine Funktion enthält, die das tut. Folglich sollte die Funktion diesen Kommentar bekommen.

[DasIch]

Bis auf die "Funktion" die in einen Docstring gehört ist alles daran redundant. Allein deswegen schon würde ich sagen dass es nicht guter Stil ist.

Ich würde sogar weitergehen und sagen es ist schlechter Stil, da man idealerweise Änderungen nur über PRs mit Code Reviews von mindestens einem Kollegen macht. Wenn du jetzt bei jedem Code Review einen Diff mit irrelevanten Kram drin hast, ist dies nicht sonderlich toll.

Die Version ist im Zweifel sowieso nicht im Code weil sie durch ein CI/CD System vergeben wird, in unserem Fall erzeugt dies auch gleich einen git tag. Damit kannst du sie ohnehin nicht in einem Kommentar haben und die Frage ob es eine __version__.py o.ä. geben sollte erübrigt sich auch. Wenn auch ungewöhnlich im Open Source Umfeld, machen wir dies intern auch bei Libraries. Wenn man nicht mehrere major Versionen pro Tag releasen möchte, kann man da auch eine Kombination aus manuell (für major) und automatisch (für den minor Teil) nutzen.

[__deets__]

Ist aber in Versionskontrolle enthalten.

Das Tag @Author sagt nur wer die letzte Änderung gemacht hat, nicht von wem der Code hauptsächlich stammt.

Auch das ist doch in der Versionskontrolle enthalten. Welchen Mehrwert hat das also? Normalerweise geht es bei so etwas um Copyright. IANAL, aber per se hast du als Autor das erstmal, und AFAIK ist das zB eine Bedingung von diversen FOSS-Lizenzen.

Und wenn es von Interesse ist, wer als letztes etwas geaendert hat, dann doch auch *was* derjenige geaendert hat. Nur einen Parameter, oder nen neuen verrueckten ML-Algorithmus reingepackt? Fuer eine Diskussion muss dann schon auch klar sein, wie genau die Aenderung aussah -> Versionskontrolle.

[nezzcarth]

Ich kenne solche Header z.B. von RCS. Das kann ähnliche Header in einer Zeile erzeugen, die man heute noch manchmal sieht. Daher würde ich vermuten, dass das sich irgendwie aus solchen historischen Systemen in die Gegenwart gerettet hat.

[pixewakb]

Zu einem Versionskontrollsystem konnte ich mich immer noch nicht durchringen, weil ich ziemlicher Einzelkämpfer bin und ausreichend Speicherplatz besitze. D. h. ich speichere häufig die komplette Version in einem Unterordner zum Programm und benenne diesen Ordner dann entsprechend der Version.

Mich scheut vor einer Versionsverwaltung,

• * dass ich dann einen ziemlichen Overhead einsetzen müsste (weiteres Programm) - welches?
  * mich in diesem Programm einarbeiten müsste
  * ich leicht den Überblick verlieren könnte
  * ich nicht weiß, wie ich die Versionsverwaltung wieder gesichert bekomme

Eine Versionsverwaltung müsste für mich komplett lokal arbeiten können und die zugehörige(n) Datei(en) müssten sich einfach sichern lassen. Ich weiß, dass ich bei PyCharm schon mal lokal etwas eingecheckt (?) habe, ganz warm bin ich damit aber nicht geworden.

Ich habe ein MediaWiki lokal installiert und ich packe da sowohl den Quellcode rein, als auch eine Versionsgeschichte, die ich händisch pflege. Ich betreue eine ganze Fülle von Tools, die in einzelnen Ordnern liegen und kleine Teilaufgaben lösen. Wenn ich dann für jeden Teilordner erst eine Software starten müsste, um zu gucken, was ich gemacht habe, wäre das sehr unangenehm.

----------------------------------------------------------------------------------------------------------------------------------

Ich verstehe Eure Beiträge so, dass ich auf diese Meta-Daten in einer Datei verzichten kann und sollte und auch __versions__.py keinen Mehrwert bietet. Ich würde das dann so umsetzen.

[__deets__]

Ich arbeite mit git auf dutzenden, eher fast schon hunderten Repositories. Das ist gerade fuer einfache Faelle von nur-meine-eigenen-Aenderungen-ohne-grosses-gehummse verwalten an Trivialitaet nicht zu ueberbieten. Wenn du dir dann noch auf einem Netzwerk-Share diese Repositories als "remote" anlegst, dann hast du mit

- bearbeite datei
- git add datei
- git commit -m "voll toll was getan"
- git push

von einer neuen Version bis hin zur Sicherung alles erledigt. Wenn das schon zu viel des guten ist - dann hilft auch kein professionelles-programmier-placebo ala eines dicken Headers voll redundanter Information. Der hat mehr Zeilen....

Ein Repository anlegen geschieht mit

- git init

Das ist zumindest fuer das lokale arbeiten schon alles was zu tun ist. Erst wenn Sicherung etc. dazu kommen, muss man sich ein remote anlegen, was aber auch einfach nur ein Ordner unter git-Verwaltung ist. Gross mit Servern etc. muss man da ueberhaupt nichts aufsetzen (anders als bei SVN oder CVS).

Alles, was bei mir nicht von vorne herein eh im /tmp fuer das baldige Verschwinden an Skripten geschrieben wird, bekommt ein "git init" verpasst. Und bei bestaendigerem Wert eben ein remote, in letzter Zeit zunehmend auch auf meiner Dropbox - die ist eh da.

[noisefloor]

Hallo,

falls man das Skript publik macht, dann sollte auf jeden Fall noch die Lizenz erwähnt werden.

Wenn ich mal ein Skript von mir publik mache (was selten vorkommt), dann trage ich mich bei `__author__` als Autor ein und bei `__version__` ein Versionsnummer, in der Regel das Datum der Veröffentlichung rückwärts (also z.B. 20180503). Bei meinen privaten Skripten trage ich das alles nicht ein, halte ich für den Privatgebrauch für überflüssig.

Gruß, noisefloor

[Sirius3]

@pixewakb: Du solltest Dich dringend in ein Versionskontrollsystem einarbeiten. Die Stunde Einarbeitung und der minimale Mehraufwand rechnet sich in kurzer Zeit, weil Du Dir keine Gedanken und Arbeit mehr mit Versionen, Sicherungskopien etc. machen mußt. Und wenn irgendwann einmal etwas schief geht, sparst Du Dir Stunden, mit Suchen, was Du wann irgendwohinkopiert hast.
git ist komplex, es reichen aber meist die 4 Befehle, die __deets__ schon gezeigt hat.

[kbr]

@pixewakb: Wenn Du einmal git (oder mercurial) verwendet hast, wirst Du es nicht mehr missen wollen. Der Lernaufwand lohnt sich, und für die Basics ist er auch überschaubar. Hier findest Du einen Einstieg: https://de.atlassian.com/git.

[pixewakb]

Ok, ich schaue es mir gerne an!!!

Erst einmal danke für die Antworten!!!

[RIN67630]

Wäre es nicht sinnvol hinein zu schreiben für welche Python-Version der Code geschrieben wurde?
Dann auch die Abhängigkeiten und ggf. die Hardwarevorraussetzungen angeben.

[kbr]

@RIN67630: Einen Hinweis auf Hardwareabhängigkeiten brauchst Du selten. Ein Hinweis auf die minimale Python Version kann sinnvoll sein, lässt sich aber auch als Test einbauen, mit entsprechendem Hinweis, wenn eine unpassende Version erkannt wird. Abhängigkeiten lassen sich an den import Statements erkennen, weswegen diese auch in wohlgeordneter Reihenfolge an den Anfang jedes Moduls gehören. Bei umfangreichen Projekten übernimmt die Dokumentation der Abhängigkeiten zudem eine requirements Datei, in der alle erforderlichen Packages mit passenden Versionsnummern gelistet sind, so dass diese beispielsweise direkt von pip verwendet werden kann. Der Kommentarkopf aus dem Buch von Weigend war sicher einmal sinnvoll, ist heute bei Python-Programmen in der Form aber nicht mehr üblich. Auch in der siebten Auflage befindet sich in dem Buch noch einiges an Altlasten; dennoch ist es unter den deutschsprachigen Büchern eines der besseren und mit kleinen Abstrichen durchaus empfehlenswert.