Dlaczego nie ma przeglądów kodu dla projektów typu open source? [Zamknięte]

Istnieją bardzo złożone projekty typu open source, a niektórym z nich myślę, że mógłbym wnieść jakiś wkład i szkoda, że ​​nie mogę, ale bariera wejścia jest zbyt wysoka z jednego powodu: do zmiany jednego wiersza kodu duży projekt, musisz to wszystko zrozumieć.

Nie musisz czytać całego kodu (nawet jeśli czytasz, nie będzie to wystarczające) i rozumieć, co robi każda pojedyncza linia i dlaczego, ponieważ kod prawdopodobnie jest zmodularyzowany i podzielony na części, więc istnieją abstrakcje, ale nawet wtedy musisz uzyskać przegląd projektu, abyś mógł wiedzieć, gdzie są moduły, gdzie jeden moduł łączy się z drugim, co dokładnie robi każdy moduł i dlaczego oraz w jakich katalogach i plikach dzieje się każda z tych rzeczy.

Nazywam ten przegląd kodu , jako nazwę sekcji, którą projekty open source mogłyby mieć na stronie internetowej lub w dokumentacji wyjaśniającej ich kod osobom postronnym. Myślę, że przyniosłoby to korzyści potencjalnym współpracownikom , ponieważ byliby w stanie zidentyfikować miejsca, w których mogliby budować, rzeczywistych zaangażowanych koderów , ponieważ byliby w stanie, pisząc wszystko, reorganizować swoje umysły i pomagać użytkownikom , tak jak robiliby to być pomocnym w zrozumieniu i lepszym zgłaszaniu napotkanych błędów, a może nawet przyczynić się.

Ale wciąż nie widziałem żadnego z tych „przeglądów kodu”. Dlaczego? Czy są takie rzeczy i tęsknię za nimi? Rzeczy, które wykonują tę samą pracę, co opisuję? Czy jest to całkowicie bezużyteczny pomysł, ponieważ wszyscy, oprócz mnie, mogą łatwo zrozumieć projekty zawierające tysiące linii kodu?

Ponieważ to dodatkowy wysiłek, aby utworzyć i utrzymywać taki dokument, a zbyt wiele osób nie rozumie związanych z tym korzyści.

Wielu programistów nie jest dobrymi pisarzami technicznymi (choć wielu jest); rzadko piszą dokumenty wyłącznie do spożycia przez ludzi, dlatego nie mają praktyki i nie lubią tego robić. Napisanie przeglądu kodu zajmuje czas, którego nie można poświęcić na kodowanie, a początkowa korzyść dla projektu jest zawsze większa, jeśli można powiedzieć „Obsługujemy wszystkie trzy warianty kodowania”, a nie „Mamy naprawdę fajne wyjaśnienia naszego kodu!” Pojęcie, że taki dokument przyciągnie więcej programistów, aby na dłuższą metę napisać więcej kodu, nie jest dla nich obce , ale jest postrzegane jako niepewny hazard; czy ten tekst naprawdę zrobi różnicę między zaczepieniem współpracownika, czy nie? Jeśli Ciągle kodowania teraz , załatw to.

Dokument przeglądu kodu może również sprawić, że ludzie poczują się defensywni; ciężko jest opisać decyzje na wyższym poziomie, nie odczuwając potrzeby ich uzasadnienia, i bardzo często ludzie podejmują decyzje bez powodu, który „brzmi wystarczająco dobrze”, gdy jest napisany samodzielnie. Istnieje również efekt związany z wyżej wymienionym: ponieważ aktualizacja tekstu w celu dopasowania do zmieniającego się kodu powoduje dodatkowy wysiłek, może to zniechęcić do zamiatania zmian w kodzie. Czasami ta stabilność jest dobra, ale jeśli kod naprawdę wymaga przepisania na średnim poziomie, zamienia się w odpowiedzialność.

Sucha, surowa prawda?

Dokumentacja nie jest tworzona, ponieważ projekty mogą się bez niej obejść.

Nawet projekty open source często napotykają silną konkurencję. Większość takich projektów nie zaczyna się od dużych ramion, zaczyna się od jasnego pomysłu, często od jednego pomysłowego człowieka.

W związku z tym nie mogą sobie pozwolić na czas i koszty wynajmu ludzkich dokumentów, nawet jeśli zaoferują bezpłatną współpracę. Udokumentowany projekt, w rzeczywistości, zwykle najpierw przechodzi kilka początkowych iteracji. Często zaczyna się od 1-3, być może 5 facetów spisuje swój nowatorski pomysł i pokazuje go światu jako dowód koncepcji. Jeśli pomysł okaże się dobry, to mogą dodać „obserwatorzy”, zwykle zaczynają prosić o rozszerzenia, nowe opcje, tłumaczenia ... W tym momencie kod jest nadal prototypem, zwykle z zakodowanymi opcjami i komunikatami.

Nie wszystkie projekty open source wykraczają poza tę fazę, tylko te, które przełamują „masę krytyczną” potrzebną do przyciągnięcia zainteresowania publicznego. Co więcej, jeden z pierwszych programistów musi „myśleć daleko i daleko” i planować rozszerzenia i tak dalej. Równie dobrze mógłby zostać „ewangelistą” projektu, a czasem także „kierownikiem projektu” (innym razem są to różni ludzie). Jest to niezbędny krok do realizacji projektu, od potwierdzenia koncepcji do ustalonej w branży rzeczywistości.

Nawet wtedy kierownik projektu może nie tworzyć dokumentacji.

Dynamiczny, rozwijający się projekt byłby zarówno spowolniony, a dokumentacja naprawdę pozostawałaby w tyle za kodem, podczas gdy byłby on bardzo udoskonalany, aby wdrażać tłumaczenia, opcje, podłączać menedżerów ...

Zwykle dzieje się:

1. Powstaje krótki dokument wprowadzający na temat tego, czym jest projekt i dokąd zmierza (słynna „mapa drogowa”).
2. Jeśli to możliwe, opracowywany jest interfejs API, który jest wybierany jako „udokumentowany kod” na większą część podstawowego kodu.
3. Szczególnie API, ale także drugi kod są formatowane i dodawane są specjalne komentarze „PHPdoc” / „Javadoc” itp. Oferują przyzwoity kompromis między czasem spędzonym a nagrodą: nawet skromny programista zwykle wie, jak napisać linijkę opisującą jego funkcje, parametry są również dokumentowane „automatycznie”, a całość jest powiązana z odpowiednim kodem, dzięki czemu unikają dokumentacji ” desyncing ”i opóźnienie rozwoju.
4. Najczęściej tworzone jest forum. To potężne media społecznościowe, w których użytkownicy końcowi i programiści mogą rozmawiać ze sobą (i między swoimi rówieśnikami, być może w podforach „tylko dla programistów”). Pozwala to na zdobycie dużej wiedzy i konsolidację przez społeczność (czytaj: nie obciążanie zespołu programistów) FAQ i HOWTO.
5. W naprawdę dużych projektach powstaje również wiki. Mówię o „dużych projektach”, ponieważ często są to osoby z wystarczającą liczbą obserwujących, aby stworzyć wiki (programista robi), a następnie faktycznie wypełnić ją poza „nagimi kośćmi” (społeczność robi).

Dokumenty przeglądowe, które opisujesz, są rzadkie nawet w projektach komercyjnych. Wymagają dodatkowego wysiłku przy niewielkiej wartości dla programistów. Również programiści nie piszą dokumentacji, chyba że naprawdę tego potrzebują. Niektóre projekty mają szczęście, że mają członków, którzy są dobrzy w pisaniu artykułów technicznych, dzięki czemu mają dobrą dokumentację użytkownika. Dokumentacja programisty, jeśli istnieje, prawdopodobnie nie zostanie zaktualizowana w celu odzwierciedlenia zmian w kodzie.

Każdy dobrze zorganizowany projekt będzie miał drzewo katalogów, które jest względnie oczywiste. Niektóre projekty dokumentują tę hierarchię i / lub powody, dla których została wybrana. Wiele projektów ma względnie standardowe układy kodu, więc jeśli je zrozumiesz, zrozumiesz układ innych projektów korzystających z tego samego układu.

Aby zmienić wiersz kodu, potrzebujesz ograniczonego zrozumienia otaczającego kodu. W tym celu nigdy nie powinieneś rozumieć całej bazy kodu. Jeśli masz rozsądne pojęcie o rodzaju uszkodzonej funkcji, często możliwe jest dość szybkie poruszanie się po hierarchii katalogów.

Aby zmienić wiersz kodu, musisz zrozumieć metodę, w której znajduje się wiersz. Jeśli zrozumiesz, jakie jest oczekiwane zachowanie metody, powinieneś być w stanie wprowadzić zmiany naprawcze lub rozszerzenia funkcjonalności.

W przypadku języków zapewniających zakres można refaktoryzować metody o zakresie prywatnym. W takim przypadku może być konieczna zmiana dzwoniących, a także metody lub metod refaktoryzacji. Wymaga to szerszego, ale wciąż ograniczonego zrozumienia podstawy kodu.

Zobacz mój artykuł Dodawanie SHA-2 do Tinyca, aby zobaczyć, jak można wprowadzić takie zmiany. Mam bardzo ograniczoną wiedzę na temat kodu użytego do wygenerowania interfejsu.

Czy są takie rzeczy i tęsknię za nimi? Rzeczy, które wykonują tę samą pracę, co opisuję?

Istnieje doskonała książka zatytułowana The Architecture of Open Source Applications, która zawiera szczegółowe opisy różnych głośnych projektów oprogramowania open source. Nie jestem jednak pewien, czy dokładnie spełnia rolę, którą sobie wyobrażasz, ponieważ uważam, że jej podstawową grupą docelową są deweloperzy szukający wzorców do naśladowania podczas tworzenia własnych aplikacji, a nie nowi twórcy projektów opisanych w książce (chociaż jestem pewien, że to może być pomocne).

Ponieważ jest o wiele więcej programistów open source niż pisarzy technicznych open source.

Dokumentacja wymaga konserwacji i czasu na aktualizację. Im bardziej obszerna jest dokumentacja, tym więcej zajmuje. A dokumentacja, która nie jest zsynchronizowana z kodem, jest gorsza niż bezużyteczna: wprowadza w błąd i ukrywa zamiast ujawniać.

Dobrze udokumentowana baza kodu jest lepsza niż jedna mniej udokumentowana, ale dokumentacja może z łatwością zająć tyle czasu, ile napisanie kodu. Twoje pytanie brzmi: czy lepiej mieć dobrze udokumentowaną bazę kodu, czy bazę kodu, która jest dwa razy większa? Czy koszt aktualizowania dokumentacji za każdym razem, gdy zmiany kodu są warte wkładu dodatkowych deweloperów, które może, ale nie musi, przynieść?

Kod wysyłki wygrywa. Zmniejszenie wysiłku włożonego w rzeczy inne niż kod wysyłkowy może sprawić, że kod będzie wysyłany częściej i istnieje większe prawdopodobieństwo, że zostanie wysłany, zanim zabraknie zasobów.

To nie znaczy, że rzeczy oprócz wysyłki mają znaczenie. Dokumentacja stanowi wartość dodaną dla projektu, a przy wystarczająco dużym projekcie koszt połączenia innego programisty może być znacznie wyższy niż dodanie dokumentu. Jak wspomniano, dokumentacja może zwiększyć inwestycje w projekt (ułatwiając przyłączenie się nowych programistów).

Jednak nic nie sprzedaje się tak jak sukces: projekt, który nie działa lub nie robi niczego interesującego, rzadko przyciąga programistów.

Dokumentacja bazy kodu jest formą meta-pracy. Możesz poświęcić dużo czasu na pisanie fantazyjnych dokumentów opisujących bazę kodu, która nie ma zbytniej wartości, lub możesz spędzać czas na robieniu rzeczy, których pragną konsumenci twojej bazy kodu i aby twoja baza kodu miała wartość.

Czasami utrudnienie sprawia, że ​​ci, którzy wykonują to zadanie lepiej. Albo z powodu większego zaangażowania w projekt (spędzanie godzin na naukę architektury), albo z powodu uprzedzeń umiejętności (jeśli jesteś już ekspertem w pokrewnej technologii, przyspieszenie będzie szybsze, więc barierą braku jest takiej dokumentacji jest mniej ważne: dlatego do zespołu dołącza więcej ekspertów, a mniej początkujących).

Wreszcie, z wyżej wymienionych powodów, obecni programiści mogą być ekspertami w dziedzinie kodu. Pisanie takiej dokumentacji nie pomaga im w znacznym stopniu zrozumieć podstawy kodu, ponieważ mają już wiedzę, pomaga tylko innym programistom. Znaczna część rozwoju oprogramowania typu open source opiera się na „drapaniu się” w kodeksie: brak dokumentacji, która już mówi, co deweloper rzadko swędzi.

Oprócz dodatkowego wysiłku , niektóre projekty open source celowo rujnują swoją dokumentację, aby uzyskać wolne miejsca pracy dla ich opiekunów (aby coś wdrożyć lub przeprowadzić szkolenia). Nie tylko nie mają przeglądu kodu, ale ich interfejs API i samouczki są złe lub brakuje wielu rzeczy.

Wystarczy wymienić jeden dość popularny: bluez. Powodzenia w znalezieniu dobrego samouczka, innego niż skanowanie w poszukiwaniu pobliskich urządzeń.