Wann immer ich eine API in Java entwickeln muss, beginne ich normalerweise damit, meine IDE zu öffnen und die Pakete, Klassen und Schnittstellen zu erstellen. Die Methodenimplementierungen sind alle dumm, aber die Javadocs sind detailliert.
Ist das der beste Weg, um etwas zu unternehmen? Ich fange an zu fühlen, dass die API-Dokumentation die erste sein sollte, die erstellt wird - noch bevor die erste .java-Datei geschrieben ist. Das hat wenige Vorteile:
Gibt es andere, die diese Meinung teilen? Und wenn ja, wie gehen Sie mit dem API-Design vor?
Gibt es da noch Tools, die helfen könnten? Vermutlich sogar eine Art annotierungsbasiertes Werkzeug, das Dokumentation erzeugt und dann die Skelettquelle (Art von Modell-zu-Code-Generatoren)? Ich stieß auf Eclipse PDE API Tooling - aber dies ist spezifisch für Eclipse-Plugin-Projekte. Ich habe nichts allgemeineres gefunden.
Für eine API (und für viele Arten von IMO-Problemen) ist ein Top-Down-Ansatz für Problempartitionierung und -analyse der richtige Weg.
Allerdings (und das ist nur meine 2c basiert auf meiner eigenen persönlichen Erfahrung, also nimm es mit einem Körnchen Salz), konzentriert sich auf den Javadoc Teil davon ist eine gute Sache zu tun, aber das ist immer noch nicht ausreichend und kann nicht zuverlässig der Ausgangspunkt sein. In der Tat ist das sehr umsetzungsorientiert. Was ist also mit dem Design, der Modellierung und der Argumentation passiert, die davor stattfinden sollten (wie kurz auch immer das sein mag)?
Sie müssen eine Art von Modellierung durchführen, um die Entitäten (die Substantive, Rollen und Verben) zu identifizieren, aus denen Ihre API besteht. Und egal, wie "agil" man sein möchte, solche Dinge können nicht ohne ein klares Bild der Problemaussage (selbst wenn es nur eine 10K-Fuß-Ansicht davon ist) erstellt werden.
Der beste Ausgangspunkt ist, zu spezifizieren, was Sie zu implementieren versuchen, oder genauer gesagt, welche Art von Problemen Ihre API versucht anzugehen. BDD könnte hilfreich sein (mehr dazu unten). Das ist, was Ihre API (Bezugselemente) und an wen, welche Aktionen (die Verben) und unter welchen Bedingungen (der Kontext) liefern wird. Das führt dann dazu, zu identifizieren, welche Entitäten diese Dinge bereitstellen und unter welchen Rollen (Schnittstellen, insbesondere Schnittstellen mit einer einzigen, klaren Rolle oder Funktion, nicht als Sammelbecken von Methoden). Das führt zu einer Analyse, wie sie zusammen orchestriert werden (Vererbung, Zusammensetzung, Delegierung, etc.)
Sobald Sie das haben, können Sie in der Lage sein, ein vorbereitendes Javadoc zu machen. Dann können Sie mit der Implementierung dieser Schnittstellen dieser Rollen beginnen. Mehr Javadoc folgt (zusätzlich zu anderen Dokumentationen, die nicht in Javadoc .ie. Tutorials, How-tos, etc.) Fallen.
Sie beginnen Ihre Implementierung mit Use Cases und überprüfbaren Anforderungen und Verhaltensbeschreibungen, was jede einzelne Aufgabe alleine oder in Zusammenarbeit tun sollte. BDD wäre hier sehr hilfreich.
Während Sie daran arbeiten, refobieren Sie kontinuierlich, hoffentlich indem Sie einige Metriken (zyklomatische Komplexität und einige Varianten von LCOM) nehmen. Diese beiden sagen dir, wo du umgestalten solltest.
Eine Entwicklung einer API sollte sich nicht von der Entwicklung einer Anwendung unterscheiden. Schließlich ist eine API eine utilitaristische Anwendung für einen Benutzer (der zufällig eine Entwicklungsrolle hat.)
Daher sollten Sie das API-Engineering nicht von der allgemeinen softwareintensiven Anwendungstechnik unterscheiden. Verwenden Sie die gleichen Praktiken, stimmen Sie sie nach Ihren Bedürfnissen ab (was jeder, der mit Software arbeitet, tun sollte), und Sie werden es schaffen.
Google hat seine Videogesprächsreihe "Google Tech Talk" seit einiger Zeit auf youtube hochgeladen. Einer von ihnen ist eine einstündige Vorlesung mit dem Titel "Wie man eine gute API gestaltet und warum es wichtig ist" . Vielleicht möchten Sie es auch überprüfen.
Einige Links, die Ihnen helfen könnten:
Google Tech Talks "Beyond Test Driven Development: Verhaltensorientierte Entwicklung": Ссылка
Verhaltensgetriebene Entwicklung: Ссылка
Website-Begleiter zum Buch "Practical API Design": Ссылка
Zurück zu den Grundlagen - Strukturiertes Design # Zusammenhalt und Kopplung: Ссылка
Die Definition der Schnittstelle ist zunächst die Programmierung von Vorbedingungen, Nachbedingungen und Invarianten. Ich finde, dass es gut mit Test-Driven-Development (TDD) kombiniert, weil die Invarianten und Nachbedingungen, die Sie zuerst schreiben, die Verhaltensweisen sind, nach denen Ihre Tests suchen können.
Nebenbei bemerkt scheint es, dass die behavior-driven-development-Ausarbeitung von TDD durch Programmierer entstanden ist, die normalerweise nicht zuerst an die Schnittstelle gedacht haben.
Was mich betrifft, bevorzuge ich immer mit dem Schreiben der Schnittstellen zusammen mit ihrer Dokumentation und beginne erst mit der Implementierung.
In der Vergangenheit habe ich einen anderen Ansatz gewählt, der mit der UML anfing und dann die automatische Code-Generierung verwendete.
Das beste Werkzeug, das ich in dieser Hinsicht kennengelernt habe, war
Ich spring direkt mit der Codierung mit einem Prototyp. Irgendwelche erforderlichen Schnittstellen erscheinen bald bei Ihnen und Sie können Ihr Proto zu einem Endprodukt formen. Erhalten Sie Feedback auf dem Weg von wem auch immer Ihre API verwenden wird, wenn Sie können.
Es gibt keinen "besten Weg", sich dem API-Design zu nähern, was auch immer für Sie funktioniert. Domänenwissen spielt auch eine große Rolle.
Ich bin ein großer Fan der Programmierung der Schnittstelle. Es bildet einen Vertrag zwischen den Implementierern und den Benutzern Ihres Codes. Anstatt direkt in Code einzutauchen, beginne ich normalerweise mit einem Basismodell meines Systems (UML-Diagramme usw., abhängig von der Komplexität). Dies ist nicht nur eine gute Dokumentation, sondern auch eine visuelle Klärung der Systemstruktur. Dadurch wird der Codierteil viel einfacher zu machen. Diese Art von Design-Dokumentation macht es auch einfacher, das System zu verstehen, wenn Sie in 6 Monaten darauf zurückkommen oder versuchen, Fehler zu beheben :) Prototyping hat auch seine Vorzüge, aber sei bereit, es wegzuwerfen und neu anzufangen.
Tags und Links java javadoc api-design topdown