Wolę przykłady niż dokumentację. Czy to problem behawioralny?

Ilekroć spotykam nowy interfejs API lub język programowania, a nawet proste strony podręcznika systemu Linux , zawsze (odkąd pamiętam) unikałem ich i zamiast tego leniwie polegałem na przykładach pozwalających na zrozumienie nowych koncepcji.

Podświadomie unikam dokumentacji / API, gdy nie jest to proste, tajemnicze lub zwykłe nudne. Minęły lata, odkąd zacząłem programować i teraz czuję, że muszę naprawić swoje sposoby, ponieważ teraz zdaję sobie sprawę, że powoduję więcej szkód, powstrzymując się od czytania tajemniczej / trudnej dokumentacji, ponieważ wciąż jest milion razy lepsza niż przykłady jako oficjalne dokumentacja ma większy zasięg niż jakikolwiek inny przykład. Nawet po uświadomieniu sobie, że przykłady należy traktować jako „wartość dodaną” zamiast „podstawowego” źródła uczenia się.

Jak mogę zerwać z tym złym nawykiem jako programista, czy też zbytnio się zastanawiam?

Nawyk polegania na preferencjach na przykładach nie ma nic złego: dla ciebie to tylko najszybszy sposób na uzyskanie odpowiedzi. Ponadto przykłady są wizualne. Łatwiej jest parsować wizualnie przykład niż czytać akapity tekstu i wyodrębniać potrzebne informacje.

Przykład:

Aby wyświetlić listę produktów, należy użyć Indexakcji Productskontrolera, biorąc pod uwagę, że GETjest to jedyny możliwy czasownik tutaj (patrz [Wpływ na produkty], aby uzyskać więcej informacji na temat działań służących do tworzenia, modyfikowania i usuwania produktów z bazy danych).

Aby uzyskać szczegółowe informacje o konkretnym produkcie, dołącz jego unikalny identyfikator na końcu identyfikatora URI. Jeśli chcesz uzyskać listę każdego dostępnego produktu, nie dołączaj niczego. Możesz także użyć filtrów, jak opisano w części [Filtry REST do wybierania danych] w instrukcji. Pamiętaj, że lista produktów jest ograniczona do tysiąca pozycji. [Paginacji] można użyć do przejścia całej listy, biorąc pod uwagę, że każda strona jest nadal ograniczona do tysiąca pozycji.

Możesz także wymusić na usłudze odświeżenie ilości w magazynie. Odbywa się to poprzez ustawienie na refresh-quantitiesjeden.

jest szczegółowy, ale nudny i ledwo czytelny. Fakt, że musisz podążać za linkami, jeszcze gorzej. Jeśli dodamy kilka próbek, łatwiej będzie zrozumieć:

GET Products / Index /
GET Products / Index / 12345 /
GET Products / Index /? Skip = 100 & take = 20
GET Products / Index /? Kategoria = 12
GET Products / Index /? Cena = 0..39.90
GET Products / Index /? kategoria = 12 i pomiń = 100 i weź = 20

Problemem może być fakt, że korzystasz tylko z przykładów. Nie przestawaj po prostu używać przykładów, ale pamiętaj, że gdy wpadniesz na ten pomysł, może pomóc bardziej szczegółowa dokumentacja. Na przykład powyższa próbka nie pokazuje, że lista produktów jest ograniczona do 1 000: musisz przeczytać w tym celu dokumentację.

Kiedy wiesz, że powinieneś przeczytać dokumentację?

Za każdym razem, gdy interfejs API lub biblioteka nie działa zgodnie z oczekiwaniami. Na przykład pobierasz próbkę i wykonujesz:

POBIERZ Produkty / Indeks /? Pomiń = 6000 i weź = 3000

Z jakiegoś powodu zwraca mniej niż 3 000 pozycji, a ty masz w bazie danych ponad dwadzieścia tysięcy produktów. Tutaj interfejs API nie zachowuje się tak , jak się spodziewałeś, więc nadszedł czas, aby przeczytać szczegółową dokumentację.

Informacje dostarczone przez dokumentację można podzielić na trzy kategorie:

• Przepis.
• Odniesienie.
• Wiedza ekspercka.

Przepisy lub przykład stanowią pomost między domeną problemów a funkcjonalnościami oprogramowania. Dokumentacja opisuje całkowicie niektóre funkcje i jest przydatny, jeśli chcesz dostosować przepis do konkretnego przypadku.

(Wiedza ekspertów odwzorowuje pojęcia dziedziny problemowej na pojęcia dokumentacji, przydatne jest, jeśli pojęcia można wyrazić na kilka sposobów lub jeśli użytkownicy oprogramowania nie są ekspertami w tej dziedzinie.)

Jak mogę zerwać z tym złym nawykiem jako programista, czy też zastanawiam się nad tym? Doceniana jest wszelka mądrość innych programistów.

Nie sądzę, że twój nawyk jest zły. Kiedy uczysz się API, najpierw orientujesz się, które problemy można rozwiązać i jakie metodologie są dostępne za pomocą Recipes (twoje przykłady). Dokumentacja referencyjna pomaga następnie dostroić metodologię do specjalnych przypadków.

Przykładami są dokumentacja. Nie sądzę, że jest to złe z punktu widzenia API. Jeśli jest to jedyna dokumentacja, na którą patrzysz, może to stanowić problem. Większość przykładów skąpi na sprawdzaniu błędów, co może prowadzić do zbyt kruchego kodu, jeśli nie cofniesz się i nie wybierzesz brakujących elementów z dokumentacji referencyjnej.

Różni ludzie uczą się lepiej na różne sposoby. Niektórzy ludzie są tacy jak ty i uczą się lepiej na podstawie przykładów. Niektórzy ludzie są tacy jak ja i uczą się lepiej na podstawie szczegółowej dokumentacji. Umieszczenie obu w dokumentacji wydaje się całkiem dobrze obejmować większość programistów. Porozmawiaj z nauczycielem, może ci powiedzieć na kilka sposobów, jak ludzie się uczą.