Wann ist eine API überentwickelt?

Question

Ich verachte die Arbeit mit überentwickelten APIs, die einfache Dinge nicht einfach machen. Nichtsdestotrotz arbeite ich an der Entwicklung einer API für eine Open-Source-Bibliothek und ich fange an zu fühlen, dass ich in die Overengineering-Falle falle. Ich kann es wirklich nicht genau sagen, denn natürlich habe ich das verdammte Ding geschrieben, also ist es für mich offensichtlicher als jeder andere. Was sind einige Warnsignale aus der Sicht eines Entwicklers, dass Ihre API möglicherweise überentwickelt ist?

Answer 1

"Was sind einige Warnzeichen aus der Sicht eines Entwicklers, dass Ihre API möglicherweise überentwickelt ist?"

Keine Anwendungsfälle.

Wenn Sie nicht laufen durch einfaches können Szenarien „dies zu tun“, sind Sie nicht eine nützliche API mit spezifischen Anwendungsfällen im Auge zu entwerfen.

Ihre Dokumentation sollte diese Anwendungsfälle sein.

Eigenschaften, die nicht direkt die Anwendungsfälle befassen sich wahrscheinlich Over-Engineering.

Answer 2

Zwei (bezogen) Fragen zu stellen, sich sofort in den Sinn kommen:

• Gibt es Dinge, die in mehr als einer Weise getan werden kann?
• Gibt es Methoden/Eigenschaften in der API, die in Bezug auf den Rest der API ausgedrückt werden können?

Schwieriger zu beantworten, und nicht ein Zeichen von Overengineering an sich, aber auf jeden Fall ein Zeichen der API nicht so einfach ist, wie es noch sein könnte:

• Gibt es andere Methoden/Eigenschaften, die Sie kann vorstellen, dass es möglich wäre, mehr als Sie eingeführt (basierend auf den anderen beiden Fragen) zu entfernen

Answer 3

Wenn die Dokumentation und Beispiele der Überprüfung auf den Prozentsatz der Wortschwall der Anteil der Wortschwall der API in Bezug auf sich selbst diskutieren cmpared ihre Anwendung auf glaubhafte Anwendungsfälle zu diskutieren.

Answer 4

Wie S.Lott sagte, Anwendungsfälle. Sie bestimmen, worauf genau Ihre API ausgerichtet sein sollte. Wenn Sie Ihre API so konzipieren, dass sie ein sehr klares, spezifisches Ziel erfüllt - functionally coherent -, werden Sie höchstwahrscheinlich mit einer API oder Komponente in Ihrer API enden, die sowohl einfach zu verwenden als auch zu verstehen ist.

Das Entwerfen einer API sollte dem Entwerfen einer Benutzerschnittstelle ähneln. Die meisten Konzepte von UI können von einer API umschlossen werden, beispielsweise dem KISS-Prinzip oder sogar Kaizen.

Ich würde mit diesen UI-Konzepten verknüpfen, aber ich bin ein neuer Benutzer, so dass sie mich nicht mehr als 1 Hyperlink veröffentlichen lassen. Gutes Beispiel dort: StackOverflow, lass es uns wissen bevor wir posten;).

Answer 5

Sie sollten die Google Tech Talk How To Design A Good API and Why it Matters von Joshua Bloch überprüfen ... er deckt eine Menge dieses Zeug.

Answer 6

Wenn es so clever ist, dass es niemand anders verstehen kann.

Answer 7

Wenn der Stack-Trace für einen allgemeinen API-Aufruf erfordert Sie einen Bildlauf auf dem Bildschirm, um die gesamte Sache zu sehen.

Answer 8

Beginnen Sie sich zu sorgen, wenn Sie eine große API mit vielen Funktionen haben, die sich bei näherer Betrachtung als einfachere Operationen herausstellen. Eine API mit einem hohen Verhältnis von Kompositionsmechanismen zu Primitiven ist normalerweise ein gutes Design.

(API Design ist sehr ähnlich wie die Sprache Design, und ich hier im Wesentlichen bin espousing die Philosophie Schema — statt mehr Routinen in die API Spundwände, vereinfachen sie und umfassen Zusammensetzung Mechanismen, die die zusätzlichen Routinen unnötig machen.)

Answer 9

Ein Trick, den ich sehr nützlich fand und es hat mir in der Vergangenheit geholfen, doc vor, während und nach dem Programmieren zu schreiben.

Beim Entwerfen einer API, die von anderen verwendet werden soll, dokumentiere ich normalerweise das Design, bevor ich Code schreibe. Wenn ich das Design überstünde, wäre die Design-Spezifikation normalerweise voll von Konflikten und Unsinn.

Während des Codierens stehe ich normalerweise den Klassendefinitions- und Funktionskörper aus und fange an, doxygen Kommentare für sie zu schreiben. In den Kommentaren verwende ich Anwendungsfall, Beispielcode und Annahmen der Schnittstellen. Während dieser Phase, bevor zu viel realer Code geschrieben wurde, wurde die Klassenschnittstelle in der Regel mehrmals neu gestaltet. Ich weiß, dass ich über Engineering war, wenn der Beispielcode schwer zu schreiben ist und es mir schwer fällt, die Schnittstelle zu erklären. Viele der schlechten Design-Ideen werden aufgedeckt und beseitigt, wenn Sie versuchen, den Leuten zu erklären, wie Sie Ihre API verwenden.

Nach dem Codieren ersetze ich den Beispielcode in den Kommentaren mit tatsächlich kompiliertem und getestetem Code, der aus meinen Komponententests kopiert wurde, und dokumentiert das Verhalten der Schnittstelle weiter. Ein weiteres Zeichen für zu viel Engineering ist, wenn meine Komponententests nicht mit der Änderung der Schnittstelle mithalten können, da es zu viele bewegliche Teile und zu viele Möglichkeiten gibt, dasselbe zu tun, und die Einheit das Wachstum in einem exponentiellen Verhältnis testet.

Answer 10

Wenn die API ist: (1) stumpfer, komplexer, weniger effizient und weniger vorhersagbar als nur die zugrunde liegende Technologie, UND (2) für die Sicherheit keinen signifikanten Vorteil bieten, Skalierbarkeit oder plattformübergreifende Freiheit.

Answer 11

Nach meiner Erfahrung können Sie sagen, wenn das ganze Projekt für Monate gehalten wird, warten auf die API zu beenden.