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?
źródło
a million times better than examples as the official documentation has more coverage- Nie zawsze w przeszłości znalazłem kilka świetnych nieudokumentowanych funkcjiOdpowiedzi:
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:
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ć:
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:
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ę.
źródło
Informacje dostarczone przez dokumentację można podzielić na trzy kategorie:
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.)
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.
źródło
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ódło
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ą.
źródło