Czy powinienem ustawić środowisko dla kogoś, kto korzysta z mojej biblioteki?

Question

Mam tej debaty z przyjacielem, gdzie mam biblioteki (jego python, ale nie uwzględniłem jako tag, jak pytanie dotyczy dowolnego języka), który ma kilka zależności. Debata dotyczy tego, czy zapewnić domyślne środowisko podczas inicjowania, czy zmusić użytkownika kodu do jednoznacznego ustawienia.

Moja opinia to wymuszenie na użytkowniku jego wyraźnej woli i uniknięcie pomyłki oraz wyjaśnienie, do czego zmierza.

Mój przyjaciel jest bezpieczniejszy i wygodniejszy, niż domyślny w stosunku do środowiska i pozwala użytkownikowi zignorować, jeśli chce.

Myśli? Czy istnieją dobre referencje lub przykłady/wzorce w popularnych bibliotekach, które wspierają którąś z naszych argumentów? także wszelkie popularne blogi lub artykuły omawiające ten punkt projektowania interfejsu API?

Answer 1

Nie mam żadnych referencji, ale oto moje przemyślenia jako potencjalnego użytkownika wspomnianej biblioteki.

Uważam, że dobrze jest mieć domyślną konfigurację, aby umożliwić programistom szybką ocenę biblioteki. Nie chcę przechodzić przez garść konfiguracji tylko po to, by zobaczyć, czy biblioteka zrobi to, czego potrzebuję. Kiedy jestem szczęśliwy, że biblioteka zrobi to, co jest mi potrzebne, z przyjemnością skonfiguruję ją tak, jak chcę.

Dobrym przykładem jest platforma ASP.Net MVC firmy Microsoft. Podczas tworzenia nowego projektu MVC łączy się on z domyślnym uwierzytelnieniem i dostawcą członkostwa, co pozwala programiście bardzo szybko uzyskać działającą aplikację. Łatwo jest również skonfigurować różnych dostawców, które będą używane, jeśli domyślne nie spełniają wymagań danej aplikacji.

Jako nieco inny przykład, Atlassian Confluence to oprogramowanie wiki, które obsługuje wiele różnych baz danych zaplecza. Atlassian mógł zdecydować, że nie ma domyślnej konfiguracji DB, ale zamiast tego Confluence jest dostarczany z domyślną, prostą bazą danych opartą na plikach, aby umożliwić użytkownikom ocenę oprogramowania. W przypadku instalacji produkcyjnych możesz podłączyć się do Oracle, SQL Server, mySQL lub cokolwiek innego.

Może się zdarzyć, że domyślna konfiguracja biblioteki nie ma większego sensu, ale myślę, że byłby to przypadek specjalny, a nie ogólna.

Answer 2

To zależy. Jeśli możesz podać rozsądne wartości domyślne, możesz to zrobić: ułatwi to życie okazjonalnemu użytkownikowi biblioteki, ponieważ może ustawić tylko odpowiednie ustawienia, w przeciwieństwie do całego środowiska (z możliwymi ustawieniami, których konsekwencje nie rozumiem w pełni (jeszcze)). Masz rację, że w sytuacjach, w których jest to możliwe, prowadzi to do frustracji i zamieszania, ponieważ domyślne ustawienia mogą spowodować nieoczekiwane zachowanie (niespodziewane dla (niedoświadczonego) użytkownika) - musisz zważyć obniżoną frustrację z wygody w stosunku do ceny Rozumiemy, że domyślnie dokonujemy wyboru dla każdego z tych domyślnych ustawień, które mogą wpłynąć na wybór innych powiązanych ustawień. Z drugiej strony, jeśli nie ma rozsądnej wartości domyślnej (np. poświadczenia bazy danych, adres zdalny), należy wymagać od użytkownika podania tych ustawień.

Kluczem w obu przypadkach jest dostarczenie wystarczającej ilości informacji w dokumentacji biblioteki oraz w komunikatach o błędach (w przypadku brakujących ustawień lub konfliktów), że użytkownik może dowiedzieć się, co te ustawienia właściwie oznaczają/kontrolują bez konieczności przeczytaj kod źródłowy biblioteki.Ta część jest trudna, ponieważ 1) jest nudna z punktu widzenia twórcy biblioteki (więc często jest pobierana) i 2) dokumentacja musi być napisana ze sposobu myślenia początkującego do biblioteki, która często jest inna ze sposobu myślenia twórcy biblioteki - ten ostatni zna niejawne powiązania/implikacje, ten pierwszy musi być mówiony o tych w zrozumiały sposób.

Answer 3

Chociaż nie jest to dokładnie identyczne pod względem domeny problemowej, to uderza mnie jako argument Convention over Configuration.

W ostatnich latach sporo się działo za CoC, a moim zdaniem ma to wiele sensu. Dopóki elastyczność nie zostanie utracona, masz wszystko, co możesz zyskać. Niższy rozwój tarcia jest tym, po co wszyscy jesteśmy i jeśli muszę skonfigurować każdy aspekt twojego interfejsu API, aby działał, jestem mniej skłonny do używania go z innym API o takiej samej funkcjonalności.

Podobno podoba mi się podcasty Hanselmana, więc jeśli chcesz trochę posłuchać, sprawdź this podcast.

Answer 4

Myślę, że twoje pytanie wymaga pewnych wyjaśnień. Na początek nie sądzę, że biblioteka powinna mieć konfigurację środowiska wykonawczego. Pod względem zależności, zależności bibliotek powinny być obsługiwane w sposób właściwy dla środowiska, dla którego są pisane. W pythonie zależności te powinny znajdować się w pliku setup.py (pod wymaganiami), a docelowo ten plik powinien spełniać wymagania jakiejkolwiek usługi, na której planujesz udostępnić (np. Pypi dla Pythona).

W przypadku aplikacji jest całkowicie w porządku wymagać konfiguracji środowiska wykonawczego, ale powinieneś spróbować mieć rozsądne wartości domyślne. Jeśli twoja aplikacja zależy od bibliotek, ta zależność powinna być obsługiwana w taki sam sposób, w jaki będzie obsługiwana zależność od biblioteki, nawet jeśli informacje te mogą być nadmiarowe w kontekście instalatora (jeśli to konieczne). W większości przypadków skrypty pierwszego uruchomienia i ich funkcje powinny być niezależne od instalatora/rpm.

W przypadku platform sieciowych jest rzeczą typową, że aplikacja zawiera konfigurację i prawdopodobnie będzie wymagać instalacji w inny sposób niż aplikacje tradycyjne. Tutaj, jedyną rzeczą, którą możesz zrobić, to postarać się przestrzegać konwencji z jakiejkolwiek struktury, w której piszesz.