Leonidas hat geschrieben:Dann zeig mal deine Dokumentation. Ist sie nicht vorhanden, dann solltest du dich selbst fragen warum.
Für von mir selbst geschriebenen Code brauche ich auch keine Dokumentation (wobei ich bei komplexeren Funktionen mindestens aufschreibe, was für Parameter übergeben werden und was am Ende raus kommt. Schon alleine, weil ich zu faul bin die Datei rauszukrammen, wenn ich nach ein paar Monaten die Funktion wieder verwenden möchte).
Leonidas hat geschrieben:Letztendlich läuft es darauf hinaus, dass die Programmierer eben lieber Programmieren als Dokumentieren (und in der Regel auch keine guten Buchschreiber sind).
Das kann ich natürlich nachvollziehen. Allerdings sollte es doch möglich sein, "wenigstens" eine halbwegs vollständige API-Dokumentation zu schreiben. Von gut formulierten und verständlichen Tutorials usw. rede ich ja gar nicht. Ich finde es nur nicht besonders schön, wenn ich erst den Code lesen und verstehen muss, wenn ich ein bestimmtes Modul verwenden möchte.
Leonidas hat geschrieben:Aber ich sehe jetzt an den Dokumenten nicht, warum du sie schlecht findest.
Von den dort genannten Projekten habe ich bisher nur Twisted verwendet; ich (und ich glaube der Typ ebenfalls) finde eher, dass die Dokumentation allgemein oft schlecht ist.
Nehmen wir mal twiested.web.client als Beispiel. Der Download einer Webseite ist ja noch ganz leicht. In der
API-Dokumentation von getPage sehe ich ja, dass ich als ersten Parameter eine URL übergeben kann. Was ist aber, wenn ich mich jetzt irgendwo einloggen möchte, geht das überhaupt? Bei getPage steht nur
See HTTPClientFactory to see what extra args can be passed.
.
Wenn ich mir jetzt
__init__ von HTTPClientFactory ansehe, sehe ich das hier:
def __init__(self, url, method='GET', postdata=None, headers=None, agent='Twisted PageGetter', timeout=0, cookies=None, followRedirect=1): (source)
overridden in twisted.web.client.HTTPDownloader
Undocumented
Jetzt sehe ich wenigsten schon einmal, dass es zu gehen scheint. Was ich allerdings scheinbar erraten soll ist, was postdata, cookies und headers sein soll (string, list, dict?). Wenn ich in den
Quelltext von __init__ schaue, finde ich dann sogar das heraus.
Das gleich gilt, wenn ich wissen möchte, ob der Client https versteht. Im Endeffekt muss ich wieder in den Quelltext schauen.
Warum kann der Autor nicht zu getPage schreiben, was für Parameter man übergeben kann, und ob https, cookies usw. unterstützt werden? Mehr als 5 Minuten hätte das doch sicherlich nicht gedauert. So muss jeder, der die Funktion benutzen möchte bei jeder Sache den Quellcode ansehen.
Wobei die Dokumentation bei twisted nur teilweise schlecht ist. Das Konzept usw. ist imho gut erklärt (und
umfangreich).
veers hat geschrieben:Ist das wirklich ein Python spezifisches Problem? Ist doch fast überall so.
Mir ist es auf jeden Fall bisher nur bei Python (so stark) aufgefallen.
Leonidas hat geschrieben:Ich hatte mit der Profiler-Dokumentation kaum Probleme, aber wenn du da Verbesserungsvorschläge hast, dann immer her damit.
Zum Bespiel steht bei den Methoden meiner Meinung zu wenig und die Parameter sind teilweise schlecht oder gar nicht erklärt (was kann ich zum Beispiel mit addinfo machen? Ich wüsste nicht, wofür ich das verwenden sollte. Oder bei runctx, was kann "globals" und "locals" sein, ein dict?). Im Endeffekt war ich in der Lage hotshot zu verwenden, ich finde die Dokumentation aber trotzdem nicht optimal.
Leonidas hat geschrieben:Wer nutzt denn heutzutage noch Hotshot?
BlackJack hat geschrieben:@epsilon: Bei der `hotshot`-Dokumentation ist gleich am Anfang ein Hinweis, dass für den allgemeinen Gebrauch `cProfile` empfohlen wird, `hotshot` nicht gepflegt wird, und in Zukunft aus der Standardbibliothek verschwinden könnte. Ab da braucht's IMHO nicht mehr Dokumentation. Im Gegenteil, gute Dokumentation könnte Leute ermutigen das Modul *trotzdem* zu verwenden.
Das zählt aber imho beides nicht als Argument. Schließlich ist die Dokumentation seit Python 2.2 so, oder glaubt ihr die Dokumentation ist mit der Zeit weniger geworden
Und dann ist hotshot (soweit ich weiß) der einzige Profiler, der auf Zeilenebene statt auf Funktionsebene profilen kann. Ich bin also "gezwungen" hotshot zu verwenden, wenn ich genaue Daten haben will.
Dazu muss ich jetzt noch sagen, dass es sicher konstruktivere Wege gegeben hätte, als das was der Typ oder ich im ersten Post geschrieben haben ("so oft so extrem beschissen" kommt mir gerade etwas "hart" formuliert vor). Aber manchmal ist die Doku wirklich alles andere als gut bzw. vorhanden (siehe twisted.web.client)