Es wird darüber gesprochen, welche Syntax und Funktion Sie in einer Programmiersprache mögen. Ich werde jetzt fragen, welche Grundprinzipien oder Funktionen Sie in einer Bibliothek in Ihrer Lieblingssprache (oder einer anderen Sprache) wünschen.
Ein Beispiel ist das Hinzufügen von list + = anotherList, anstatt nur list + = listElement zuzulassen (obwohl einige dies als schlechte Idee ansehen).
design
libraries
api
interfaces
Dsimcha
quelle
quelle
Antworten:
Ich würde die Best Practices befolgen, die Sie unter Entwerfen einer guten API und warum dies wichtig ist von Joshua Blosh (Google) finden . Die PDF-Version finden Sie hier .
Ihm zufolge sind Merkmale einer guten API:
quelle
Ich möchte folgendes:
Ein klar definierter Namensraum. Da C meine Hauptsprache ist, möchte ich auch, dass Makros dazu passen. Das Lösen von Konflikten in diesem Bereich ist zum Kotzen.
Wenn Sie etwas zuweisen, geben Sie mir einen offensichtlichen Hinweis darauf, dass es befreit werden muss. Dies geht zu meinem nächsten Punkt, der Dokumentation.
Dokumentieren Sie die Bibliothek. Tools wie Doxygen sind einfach und portabel. Es gibt keine Entschuldigung dafür, mir nichts zu geben, was ich generieren und durchsuchen kann.
Dokumentieren Sie undurchsichtige Typen in öffentlichen Headern. Ich werde sie trotzdem finden, sag mir, warum du nicht willst, dass ich mich mit ihnen anlege und was passieren könnte, wenn ich es tue. Wenn Sie tatsächlich Patches möchten, muss ich wissen, was Sie gedacht haben.
Lass dich nicht fallen und renne. Ich freue mich sehr über Kommentare wie "Bitte, kontaktieren Sie mich nicht. Ich habe nicht die Absicht, es beizubehalten. Dies hat mein unmittelbares Problem gelöst, vielleicht wird es Ihr Problem lösen. Es ist mir egal, ich werde nicht aktualisieren." dies und Sie können sich frei fühlen, es zu gabeln. " Ich kann dir nicht sagen, wie viel Zeit mir das spart.
Es sollte dem vorhandenen Code keine Speicherlecks oder Fehler hinzufügen. Wenn Sie nicht testen, bevor Sie Inhalte in Ihren eigenen Code übertragen, warum versuchen Sie mich dann, sie in meinen Code zu übertragen?
Wenn es sich tatsächlich um eine Bibliothek handelt, verwenden Sie eine zulässige Lizenz und seien Sie konsistent. Entscheide dich in drei Monaten nicht, dass du mehr Geld damit verdienen sollst. Das ist mehr als ärgerlich in der Nacht, bevor Sie etwas versenden und feststellen, dass Sie eine Reihe von Bibliothekscodes neu schreiben müssen, weil sich die Lizenz geändert hat. Genau das macht mich so irritiert, dass ich Ihre Inhalte unter der MIT-Lizenz erneut implementieren kann.
Seien Sie im Codierungsstil konsistent, andere Leute müssen Ihren Code lesen, um herauszufinden, was er tatsächlich tut, wenn die Dinge nicht wie erwartet funktionieren.
Verwenden Sie nicht mehr als 110 Spalten, Ihr Code muss möglicherweise an Ort und Stelle bearbeitet werden, und ich habe möglicherweise nur eine 80x25-Anzeige. Wenn Sie sich auf Registerkarten verlassen, um die Dinge „eleganter“ aussehen zu lassen, müssen Sie andere Probleme lösen.
Versuchen Sie, zumindest Ports zu berücksichtigen, wenn Sie sich nicht mit einer interpretierten Sprache befassen. Versuchen Sie auch dann, zumindest die Ports zu berücksichtigen.
Gib mir Tests. Ich hoffe, Sie haben sie, ich könnte sie anders vorschlagen und ich kann tatsächlich helfen, sie basierend auf einem Anrufdiagramm zu schreiben. Wenn ich all diese Schwierigkeiten habe, benutze sie bitte . Ansonsten bekommst du Patches, die "für mich funktionieren !!!" :) :)
Brechen Sie die API nicht, Punkt. Ich weiß, dass Sie vielleicht feststellen, dass Sie alles falsch gemacht haben, aber stellen Sie sicher, dass Dinge, die auf Sie verweisen, bei einem einfachen Update nicht kaputt gehen. Das kann einige Cruft und Kludges bedeuten, willkommen in der Welt der Bibliotheken.
Geben Sie mir eine Roadmap, damit ich Ihre Arbeit oder die Arbeit anderer nicht dupliziere.
Ich werde diesen Beitrag wahrscheinlich bearbeiten, um weitere hinzuzufügen.
quelle
getcwdordnungsgemäße Verwendung muss beispielsweise eine Schleife erstellt werden, die den Puffer erweitert, bis er groß genug ist ( siehe Beispiel ).Ich bin mehr besorgt über die weichen Funktionen einer API. Das ist:
Ich könnte ein Buch darüber korrigieren, wie diese angewendet werden oder implementiert werden, aber es reicht zu sagen, dass es nur von begrenztem Nutzen ist, wenn ein Benutzer der API sich nicht darum kümmern kann, wie sie effektiv eingesetzt werden kann. Einfachheit bedeutet nicht Einfachheit, genauso wie Eleganz nicht Onate bedeutet. Es bedeutet einfach, dass es einfach perfekt für den Job ist. Je weniger jemand hat , um darüber nachzudenken , wie die API zu verwenden, desto mehr können sie es einfach verwenden.
Wie diese aussehen, hängt von der Sprache, dem Zweck und der Zielgruppe der API ab. Das allerletzte Kriterium läuft auf das Prinzip der geringsten Überraschung hinaus. Keine Fehler, bei denen Sie nicht damit gerechnet haben. Mit jeder vernünftigen Interpretation der API erhalten Sie die gewünschten Ergebnisse.
quelle
Machen Sie einfache Dinge einfach und komplizierte Dinge möglich
Dies fasst so ziemlich jede andere Designphilosophie zusammen. Wenn Ihre Bibliothek nur komplizierte Dinge ermöglicht, werden Leute, die die einfachsten 80% der Anwendungsfälle lösen möchten, versucht sein, das Rad neu zu erfinden, anstatt sich mit Ihrer überentwickelten Monstrosität zu befassen, bei der Sie 6 verschiedene Klassen verwenden müssen, um das Äquivalent Ihrer Bibliothek zu "Hallo" zu erreichen Welt".
Wenn Ihre Bibliothek nur einfache Dinge einfach macht, werden die Leute sehr schnell verärgert, wenn sie herausfinden, dass sie ihren Code neu schreiben müssen, nur weil sie eine Anforderung hatten, die etwas abseits der ausgetretenen Pfade lag.
Die besten Möglichkeiten, dies zu erreichen, sind:
Sei liberal in dem, was du akzeptierst. Wenn Sie in einer dynamischen Sprache programmieren, verwenden Sie die Ententypisierung mit voller Wirkung. Wenn Sie in C ++ oder D programmieren, verwenden Sie nach Möglichkeit Vorlagen. Akzeptieren Sie alles, was eine einigermaßen universelle strukturelle Schnittstelle erfüllt. Zwingen Sie Ihre Benutzer nicht dazu, viel Arbeit beim Konvertieren von Daten von einem Format in ein anderes zu erledigen.
Bauen Sie Komfortfunktionen auf hoher Ebene in Ihre Bibliothek ein, bauen Sie sie jedoch transparent auf Funktionen auf niedrigerer Ebene auf und stellen Sie sicher, dass die Funktionen auf niedrigerer Ebene für Benutzer verfügbar sind, die sie benötigen.
Befolgen Sie standardmäßig das Prinzip der geringsten Überraschung, auch wenn dies die Flexibilität oder Effizienz einschränken kann. Fügen Sie bei Bedarf eine zweite Funktion mit einem ausführlicheren Namen hinzu, der die Überraschung betont, um Optimierungen oder eine größere Flexibilität zu ermöglichen.
Kapselung ist nützlich, aber sei nicht anal. Personen mit ungewöhnlichen, unerwarteten Anforderungen müssen gelegentlich unter eine Ihrer Abstraktionen gelangen, um die Arbeit zu erledigen. Andererseits sollte es schwierig sein, sich versehentlich in den Fuß zu schießen , wenn scheinbar unschuldige Konstrukte verwendet werden . Denken Sie daran, wenn Sie entscheiden, wie fest Sie Dinge abschließen möchten.
Verwenden Sie Beispiele in Ihrer Dokumentation. Dies dient sowohl dazu, Ihrem Benutzer häufige Anwendungsfälle zu veranschaulichen, als auch Sie zu zwingen, darüber nachzudenken, ob die häufigsten Fälle ausreichend rationalisiert sind.
Haben Sie vernünftige Standardeinstellungen für alles, was Sie können, aber stellen Sie sicher, dass diese Standardeinstellungen nur Standardeinstellungen sind und dass klar ist, wie Sie sie überschreiben können.
quelle
Das ist alles. Vergleichen Sie als Beispiel den Mechanismus von Pipes unter Windows und UNIX. Man bietet eine Reihe spezialisierter API-Funktionen mit einer Reihe dunkler, unnötiger oder selten verwendeter Argumente, von denen jedes einen der vielen Makro- / Konstantenwerte haben kann. UNIX verwendet grundsätzlich die vorhandene Open / Read / Write / Close-Schnittstelle sowie einige sehr einfache Methoden für bestimmte Fälle wie Socketpair () oder Pipe (). Es gibt wirklich fast nichts Neues, das Sie lernen sollten, um Pipes unter UNIX zu verwenden. Vergleichen Sie jetzt damit .
(Um fair zu sein, hat Microsoft diese Schnittstelle ursprünglich nur von IBMs OS / 2 "ausgeliehen".)
quelle