Faraday: Feature Request: explizite Methodendefinitionen für HTTP-Verben

Hallo @dduugg , anstatt die Methoden explizit zu definieren, würde ich eine dokumentationsfreundliche Lösung erkunden.
Wir verwenden auch Meta-Programming Definition in der Verbindung: https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb#L195

Funktioniert das gut mit den oben genannten Punkten?
Wenn ja, könnten wir einen ähnlichen Dokumentationsausschnitt auch für das Faraday Modul replizieren.

Hallo @iMacTia , danke für die Antwort. Ich glaube nicht, dass das Problem mit Dokumentation lösbar ist. Darf ich Ihnen die Mühe machen, auf den Widerstand gegen explizite Definitionen einzugehen? Ich denke, das würde die Diskussion besser umrahmen. Zum Beispiel ist ein Dokumentationsansatz wahrscheinlich genauso ausführlich (zählt verschiedene @!method & @!scope Direktiven zusätzlich zum method_missing Code) als die sieben einzeiligen expliziten Weiterleitungsdefs Ich schlage vor auf Faraday . Aber ich weiß nicht, ob das hier der Grund ist (Code wird viel mehr gelesen als geschrieben, daher denke ich, dass die Optimierung für den Codeschreiber sowieso ein Fehler ist).

Es sind hauptsächlich 2 Punkte, die mich mit dieser Änderung auf den Punkt bringen.

• Ich persönlich denke nicht, dass die Verwendung von delegates nur für den Code-Autor von Vorteil ist. Ich benutze Ruby seit Jahren und wie andere habe ich die prägnante Syntax dieser Sprache zu schätzen gelernt. Wenn ich Code lese und delegates finde, weiß ich sofort, was das bedeutet, und es kann möglicherweise Dutzende von Codezeilen in nur ein paar davon verdichten.
• HTTP-Verb-Proxys sind nicht die einzige Instanz in Faraday, in der wir die Metaprogrammierung nutzen, es gibt viele weitere Instanzen, die höchstwahrscheinlich unter dem gleichen Problem leiden, das Sie hier angesprochen haben, aber noch nicht bemerkt wurden. Die Zustimmung zu dieser Änderung macht entweder eine Ausnahme oder schafft einen Präzedenzfall, beides Dinge, die ich vermeiden möchte.

Aber anstatt mich auf meinen Widerstand gegen diese Änderung zu konzentrieren, würde ich lieber darüber diskutieren, welche Art von Vorteilen wir hier einführen wollen. Ich verstehe das von Ihnen beschriebene Problem vollständig und ich denke, wir sollten versuchen, es nach Möglichkeit zu lösen!
Wenn das Hauptproblem hier also die Kompatibilität mit IDEs/Tools für Codevorschläge, Autovervollständigung und Dokumentation ist, dann schlage ich einfach vor, eine alternative Lösung wie Dokumentationskommentare zu finden (wir verwenden YARD bereits ziemlich häufig).
Und Sie haben auch Recht, wenn Sie sagen, dass diese Lösung genauso ausführlich ist, obwohl ich argumentieren würde, dass ein Kommentar die Lesbarkeit nicht so stark beeinflusst wie eine Liste von Methoden und er leicht erkennbar ist.

Hallo @iMacTia , danke für deine Antwort. Wir haben zu einer anderen Bibliothek mit besserer API-Auffindbarkeit und Tool-Unterstützung gewechselt, aber ich werde meine Gedanken mitteilen, falls Sie sie nützlich finden.

• Auffindbarkeit schließt die Verwendung von Metaprogrammierung nicht aus (obwohl ich in diesem speziellen Fall denke, dass explizite def s der richtige Weg sind), aber es würde erfordern, den method_missing Ansatz zu ersetzen, wie zuvor beschrieben.
• Ich bin mir nicht sicher, ob ich das Argument delegates verstehe. Faraday scheint beim Umgang mit HTTP-Verbmethoden keine expliziten Delegatoren zu verwenden. (Die Verwirrung in diesem Punkt ist wahrscheinlich ein Code-Geruch dafür, dass die Implementierung von HTTP-Verbmethoden zu kompliziert ist).
• Wir müssen uns darauf einigen, dass delegate und dergleichen eine Hilfe für den Codeschreiber sind. Ich arbeite mit Leuten mit ein paar Jahrzehnten kollektiver Ruby-Erfahrung zusammen, und wir haben hier keine Vorteile für die Lesbarkeit des Ansatzes gefunden (auch wenn man den Zeitverlust beim Erkunden der API über Pry, YARD, Sorbet und Solargraph außer Acht lässt.) ). Es kann sich lohnen, einen Rubyisten zu beobachten, der versucht, diese API zum ersten Mal zu erkunden, zumindest in diesem speziellen Punkt.

Ich versuche nur, hier ein ehrliches (und hoffentlich nützliches) Feedback zu geben. Ich schätze immer noch die Zeit und Mühe für diesen Beitrag zu OSS.

Hey, danke für deine harte Arbeit an Faraday! Ich weiß, dass dies ein altes Problem ist, aber ich neige dazu, zuzustimmen, dass die Auffindbarkeit ein kleines Problem ist. Ich arbeite an Middleware und habe diesen Abschnitt zu meiner README-Datei hinzugefügt. Meine Bibliothek ist auf jemanden ausgerichtet, der Faraday vielleicht noch nie benutzt hat, daher ist es meine Pflicht, die Dinge zu erklären. Ich sage (etwas zögerlich), dass es nicht einfach war, die Dinge zu rätseln.

@gurgeous Ich stimme zu, dass die Dokumentation definitiv eine Front ist, an der wir einen besseren Job machen könnten (obwohl wir mit dem Start der Faraday-Website begonnen haben, dies anzugehen ), aber ich sehe nicht, wie der Vorschlag in dieser Ausgabe Ihren spezifischen Punkt lösen wird.

Vielleicht übersehe ich den Punkt, weil ich einfach daran gewöhnt bin, anders zu arbeiten, aber wenn ich nicht weiß, wie man eine Bibliothek verwendet, verlasse ich mich nicht auf die automatische Vervollständigung und das Raten, um zu wissen, was zu tun ist.
Stattdessen überprüfe ich die Bibliotheksdokumentation und, wenn das nicht hilft, tauche ich in den Code ein, um zu sehen, wie er funktioniert.

Daher denke ich, dass eine verbesserte Dokumentation (visuell oder im Code) der Weg ist, dies zu lösen.
Aber vielleicht übersehe ich hier etwas oder einen bestimmten Anwendungsfall, bei dem eine bessere Dokumentation nicht helfen würde?
Ist mein Verständnis von "Auffindbarkeit" richtig?

Ist mein Verständnis von "Auffindbarkeit" richtig?

Nicht in meinem Fall. Meine Erwartung war, ls Faraday in pry , gefolgt von $ Faraday.get usw., wenn ich in eine bestimmte Methode eintauchen wollte. Ich habe das Gefühl, dass ich dies mit jedem anderen Edelstein, den ich verwendet habe, effektiv tun konnte, da ich selten (wenn überhaupt) zu einer Dokumentationsseite navigieren musste und daher dieses Ticket öffnete. (Dies gilt zusätzlich zu den anderen oben genannten Problemen, z. B. wenn statische Analysetools Code nicht erkennen, der die Bibliothek verwendet.)

Nochmals vielen Dank, dass Sie uns zugehört haben.

Ich liebe die Faraday-Website! Vielleicht kann ich eine PR mit ein paar Vorschlägen einreichen? Gerne helfen. Ich denke, für Neueinsteiger zahlt sich dieser Aufwand immer aus. Lassen Sie es mich wissen, wenn Sie interessiert sind.

Was pry + ls Faraday angeht, bin ich auch ein Fan dieses Musters und verwende es ausgiebig. Weg von method_missing ist keine schlechte Idee. Ruby wird mit dem Aufkommen von Ruby 3, Sprachservern, RBS usw. langsam in diese Richtung gezogen. Ich denke, dies ist jedoch gegenüber Docs zweitrangig.

@gurgeous Wir _sind_ an der Dokumentation von Pull Requests interessiert, suchen das Verzeichnis docs/ mit einer Reihe von Gemfiles (und README), die verwendet werden, um die Website auf den von uns verwendeten GitHub-Seiten zu veröffentlichen. Wenn die Verwendung der Website unklar ist, öffnen Sie bitte auch ein Issue oder eine PR für _that_.

Vielen Dank, dass Sie sich um Faraday-Benutzer kümmern!

Ich liebe die Faraday-Website! Vielleicht kann ich eine PR mit ein paar Vorschlägen einreichen? Gerne helfen. Ich denke, für Neueinsteiger zahlt sich dieser Aufwand immer aus. Lassen Sie es mich wissen, wenn Sie interessiert sind.

@gurgeous absolut! Wir freuen uns immer über Hilfe bei der Verbesserung der Dokumentation oder der Website, da Dinge, die für uns Betreuer offensichtlich sind, für die Benutzer möglicherweise nicht so offensichtlich sind. Außerdem haben wir wirklich Probleme mit der Zeit und das geht oft mit Kosten für die Dokumentation einher. Tatsächlich wäre die Dokumentation in einem viel schlechteren Zustand, wenn @olleolleolle nicht die anhaltenden Bemühungen !

Am Punkt pry (cc @dduugg) habe ich es nie benutzt, daher habe ich es wahrscheinlich nicht verstanden.
Ich habe es gerade mit Ihren zusätzlichen Details versucht und mir ist aufgefallen, dass ls Faraday::Connection die dynamisch generierten Methoden als auch die delegierten anzeigt 🙌.
Mein ursprüngliches Verständnis, dass wir diese Art von Ruby-"Magie" nicht verwenden können, war also falsch, und wirklich die einzige Grenze ist die Verwendung von missing_method .

Was ich nicht sehr mochte, war die Einführung expliziter Methoden wie der folgenden:

def self.get(...)
  ...
end

def self.post(...)
  ...
end

# ... and so on ...

Aber wenn wir die Entdeckung von pry beheben können, indem wir dem Hauptmodul Faraday dynamische Definitionen oder Delegationen hinzufügen, dann ist das etwas, mit dem ich einverstanden wäre. Sorry, dass ich es nicht beim ersten Mal bekommen habe!

Keine Sorge wegen Zeitmangel. Fühlen Sie sich nie schlecht, weil Sie ein Open-Source-Maintainer sind! Wir wissen Ihre Bemühungen trotzdem zu schätzen. ich war auch schon da...

Ich werde eine Diskussion über: docs starten, um sicherzustellen, dass wir auf derselben Seite sind.

@iMacTia Woher sollte ein Benutzer wissen, dass er sich mit Faraday::Connection ? Ich bin seitdem zu einem HTTP-Gem mit einer auffindbaren API gewechselt, habe aber einen kurzen Blick auf https://lostisland.github.io/faraday/usage/ geworfen und keines der Codebeispiele verwendet es explizit (obwohl das letzte dies tut) implizit). Die Beispiele rufen hauptsächlich statische Methoden auf Faraday , aber sie werden nicht in pry gefunden. Ich kenne kein anderes Juwel, das diesen Ansatz verfolgt, und ich bin immer noch der Meinung, dass es ein Anti-Muster ist.

Danke, wie immer, dass du mir zugehört hast.