Jak zdefiniować dobre lub złe API? [zamknięte]

Nie musisz czytać dokumentacji, aby poprawnie z niej korzystać.

Znak awesome API.

Wiele standardów kodowania i dłuższe dokumenty, a nawet książki (Framework Design Guidelines) zostało napisanych na ten temat, ale wiele z tego pomaga tylko na dość niskim poziomie.

Jest też kwestia gustu. APIs może przestrzegać każdej reguły w jakimkolwiek zbiorze przepisów i nadal jest do bani, ze względu na niewolnicze przestrzeganie różnych modnych ideologii. Ostatnim winowajcą jest orientacja wzorca, w którym wzorce Singletona (niewiele więcej niż zainicjalizowane zmienne globalne) i Fabryka Wzorce (sposób parametryzacji konstrukcji, ale często implementowany, gdy nie jest potrzebny) są nadużywane. Ostatnio jest bardziej prawdopodobne, że Inwersja sterowania (IoC) I związana z tym eksplozja w liczbie małych typów interfejsów, które dodają redundantnej złożoności koncepcyjnej do projektów.

Najlepsze korepetycje dla smaku to imitacja (czytanie dużo kodu i API, dowiadywanie się, co działa, a co nie), doświadczenie( popełnianie błędów i uczenie się na nim) i myślenie (nie rób tylko tego, co modne dla własnego dobra, pomyśl zanim zaczniesz działać).

• użyteczne-odpowiada na potrzeby, które nie są już spełnione (lub ulepsza istniejące)
• Łatwe do wyjaśnienia-podstawowe zrozumienie tego, co robi, powinno być proste do zrozumienia
• podąża za jakimś modelem obiektowym jakiejś domeny problemowej lub świata rzeczywistego. Używa konstrukcji, które mają sens
• poprawne użycie wywołań synchronicznych i asynchronicznych. (nie blokuj rzeczy, które wymagają czasu)
• dobre domyślne zachowanie - w miarę możliwości pozwalają na rozszerzalność i poprawianie, ale zapewniają defaults for all that is necessary for simple cases
• przykładowe zastosowania i działające przykładowe aplikacje. To chyba najważniejsze.
• Doskonała dokumentacja
• jedz własną karmę dla psa (jeśli dotyczy)
• zachowaj ją małą lub podziel ją na segmenty, aby nie była jedną wielką zanieczyszczoną przestrzenią. Zachowaj zestawy funkcjonalności odrębne i odizolowane z kilkoma, jeśli istnieją, zależnościami.

Dobre API pozwala klientowi zrobić prawie wszystko, co jest mu potrzebne, ale nie wymaga od niego wielu bezmyślnej pracy. Przykładami "bezmyślnej zajętej pracy"byłoby inicjowanie pól struktury danych, wywołanie kilku procedur w sekwencji, która nigdy nie zmienia się bez rzeczywistego kodu niestandardowego między nimi, itp.

Najpewniejszą oznaką złego API jest to, że wszyscy twoi klienci chcą owinąć go własnym kodem pomocniczym. Co najmniej Twój API powinien dostarczyć ten kod pomocniczy. Najprawdopodobniej powinien być zaprojektowany, aby zapewnić wyższy poziom abstrakcji klienci toczą się na własną rękę za każdym razem.

Dobre API ma Model semantyczny zbliżony do tego, co opisuje.

Na przykład, API do tworzenia i manipulowania arkuszami kalkulacyjnymi Excel miałby takie klasy jak Workbook, Sheet, i Cell, metodami takimi jak Cell.SetValue(text) i Workbook.listSheets().

Zawsze lubiłem ten artykuł w kolejce pod tytułem API Design Matters

Http://queue.acm.org/detail.cfm?id=1255422

I ta kolumna również, która zajmuje się kwestiami projektowania API:

Http://queue.acm.org/detail.cfm?id=1229903

Złe API to takie, które nie jest używane przez docelową grupę odbiorców.

Dobre API to takie, które jest używane przez docelową grupę odbiorców w celu, dla którego zostało zaprojektowane.

Świetne API to takie, które jest używane zarówno przez zamierzoną grupę odbiorców, zgodnie z jej przeznaczeniem, jak i niezamierzoną grupę odbiorców z powodów nieprzewidzianych przez jej projektantów.

Jeśli Amazon opublikuje swoje API zarówno jako SOAP, jak i REST, a wersja REST wygra, nie oznacza to, że bazowe API SOAP było źle.

Wyobrażam sobie, że to samo będzie prawdą dla Ciebie. Możesz przeczytać wszystko, co chcesz o projektowaniu i spróbować swoich sił, ale test kwasu będzie używany. Poświęć trochę czasu na budowanie sposobów, aby uzyskać informacje zwrotne na temat tego, co działa, a co nie, i przygotuj się na refaktoring w razie potrzeby, aby go ulepszyć.

Dobre API to takie, które sprawia, że proste rzeczy są proste (minimalna plansza i krzywa uczenia się, aby robić najczęstsze rzeczy) i skomplikowane rzeczy możliwe (maksymalna elastyczność, jak najmniej założeń). Przeciętne API to takie, które robi jedno z nich dobrze (albo szalenie proste, ale tylko wtedy, gdy próbujesz zrobić naprawdę podstawowe rzeczy, albo szalenie potężne, ale z naprawdę stromą krzywą uczenia się itp.). Straszne API to taki, który nie robi żadnego z nich dobrze.

Jest już kilka innych dobrych odpowiedzi na ten temat, więc pomyślałem, że dorzucę kilka linków, których nie widziałem.

Artykuły

1. "A Little Manual of API Design" Jasmin Blanchette z Trolltech
2. "Definiowanie interfejsów API C++ w stylu QT" również Trolltech

Książki:

1. "skuteczna Java" Joshua Bloch
2. "praktyka programowania" Kernighan i Pike

Myślę, że dobre API powinno zezwalać na niestandardowe Hooki WE / WY i zarządzania pamięcią, jeśli ma zastosowanie.

Typowym przykładem jest własny skompresowany format Archiwum dla danych na dysku, a biblioteka innej firmy ze słabym api chce uzyskać dostęp do danych na dysku i oczekuje ścieżki do pliku, w którym może załadować swoje dane.

Ten link ma kilka dobrych punktów: http://gamearchitect.net/2008/09/19/good-middleware/

Jeśli interfejs API generuje komunikat o błędzie, upewnij się, że komunikat i diagnostyka pomogą programiście rozwiązać problem.

Oczekuję, że wywołujący API przekazuje poprawne dane wejściowe. Programista jest konsumentem wszelkich komunikatów o błędach generowanych przez API (Nie użytkownik końcowy), a wiadomości skierowane do programisty pomagają programiście debugować ich program wywołujący.

API jest złe, gdy jest źle udokumentowane .

API jest dobre, gdy jest dobrze udokumentowane i zgodne ze standardem kodowania.

Teraz są to dwa, bardzo proste i bardzo trudne punkty do naśladowania, to wprowadza jeden w obszar architektury oprogramowania. Potrzebujesz dobrego architekta, który konstruuje system i pomaga frameworkom podążać za własnymi wytycznymi.

Komentowanie kodu, pisanie dobrze objaśnionej instrukcji dla API jest Obowiązkowe.

API może być dobre, jeśli ma dobrą dokumentację, która wyjaśnia, jak z niego korzystać. Ale jeśli kod jest czysty, dobry i podąża za standardem wewnątrz siebie, nie ma znaczenia, czy ma przyzwoitą dokumentację.

Napisałem trochę o strukturze kodowania tutaj

Myślę, że najważniejsza jest czytelność, przez którą mam na myśli jakość, która sprawia, że największa liczba programistów ma sens tego, co robi kod w jak najkrótszym czasie. Ale ocenianie, który kawałek oprogramowania jest czytelny, a który nie ma tej nieopisanej ludzkiej jakości: fuzziness. Punkty, o których wspominasz, częściowo go krystalizują. Jednak w całości musi pozostać sprawą indywidualną i naprawdę trudno byłoby wymyślić uniwersalną Zasady.