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

60

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?

Fiatjaf
źródło
7
Masz na myśli dokument projektowy? Widziałem rzadki projekt z opisem każdego pakietu, ale zwykle jest to już interfejs API.
maniak zapadkowy
14
Dlaczego? Ponieważ istnieje niewiele projektów, których opiekunowie chcą zainwestować w pisanie i utrzymywanie wysokiej jakości dokumentacji, często też nie rozumieją korzyści.
Alex D
9
Dokumentacja może być nieaktualna lub niedokładna w stosunku do faktycznego zachowania. Kod nie może. Dlatego większość projektów woli kod.
Paul Draper,
5
Łatwo również nie docenić, jak wiele możesz dowiedzieć się o projekcie, jeśli ustawisz minutnik kuchenny na około 2 godziny i po prostu przeczytaj (tm).
Kos,
43
Witamy w świecie kierowanym przez społeczność: jeśli nie zostało to zrobione, to dlatego, że tego nie zrobiłeś :)
mgarciaisaia

Odpowiedzi:

60

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ść.

Kilian Foth
źródło
6
Cóż, wydaje się, że odpowiedź brzmi tak: gnunet.org/gnunet-source-overview
fiatjaf
5
Jeśli chcesz, żeby istniał, zgłoś się do niego. Cały sens projektów open source polega na tym, że ludzie mogą i powinni wnosić swój wkład, pod warunkiem, że społeczność zgodzi się, że warto je zintegrować.
keshlam
8
@keshlam - ma to sens, jeśli jesteś już uczestnikiem projektu ... ale jeśli jesteś potencjalnym współpracownikiem, który próbuje uzyskać podstawowe pojęcie o tym, jak działa kod, jesteś najgorszą osobą, którą można napisać ten dokument ....
Jon Story
13
@JonStory Twój punkt widzenia jest dobry, ale w praktyce stwierdziłem, że czasem jest też odwrotnie. W niektórych projektach kończyłem pisać dokumentację na podstawie notatek, które zrobiłem podczas nauki nieudokumentowanej bazy kodu. To była lepsza dokumentacja, ponieważ musiałem zacząć od interfejsu API, który widziałem, a następnie kopać coraz głębiej. Programiści, którzy napisali kod, mieli już w głowie model kodu, a więc mieli wiele założeń na temat tego, co ktoś już wiedziałby. Dokumentacja kogoś nowego w projekcie może być lepszą dokumentacją dla kogoś nowego w projekcie.
Joshua Taylor,
6
@JonStory: Jeśli angażujesz się w mniej niż perfekcyjnie udokumentowany projekt, i tak musisz zacząć to rozgryzać. Włączenie notatek do projektu pomaga uratować pracę następnej osoby. (Nie wiem, czy ktokolwiek użyłby obecności lub nieobecności dokumentów jako decydującego czynnika, czy wnieść swój wkład). Po prostu poprawienie komentarzy javadoc (lub równoważnych) może być cennym sposobem na rozpoczęcie pracy nad tym. Poważnie, taka jest podstawowa zasada open source: jeśli widzisz coś, co należy zrobić, ZRÓB to, zamiast czekać na kogoś innego.
keshlam
14

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).
Dario Fumagalli
źródło
2
ŁAŁ!! żyjemy (i pracujemy) w dwóch całkowicie różnych światach. Gdziekolwiek obecnie pracujesz, wynoś się stamtąd szybko i znajdź firmę (jest ich wiele), w której wykona się to poprawnie, ponieważ to faktycznie oszczędza pieniądze. Nigdy nie pozwól spiczastym menedżerom / programistom kowbojskim próbować powiedzieć ci inaczej.
Mawg
6
+1, zgadzam się z prawie wszystkimi twoimi punktami, jedyne stwierdzenie, które zdecydowanie odrzucam, to to, że parametry są dokumentowane „automatycznie” . Kiedy myślimy o wyjaśnieniach, a nie o samych ograniczeniach dotyczących składni / typu, nic nie zostaje „automatycznie udokumentowane”; wygenerowany komentarz w stylu Zwraca X do getX metody nie jest pomocne dokumentacji, to tylko wypełniacz bez żadnych dodatkowych informacji.
LUB Mapper
3
@Mawg zapewnianie dobrej dokumentacji to inwestycja, rezygnujesz z czasu programisty w zamian za (miejmy nadzieję) więcej współpracowników w przyszłości i kilka innych korzyści. Ale jak wiele tego rodzaju, warto tylko, jeśli wiesz, że istnieje duża szansa, że ​​projekt się powiedzie, a większość projektów oprogramowania się nie powiedzie. Ważne jest, aby zdawać sobie sprawę z uprzedzeń dotyczących przetrwania, gdy lamentujesz nad brakiem dokumentacji w udanych projektach.
congusbongus,
Czy to możliwe, że te projekty zawodzą, ponieważ nie dokumentują? A przez dokument mam na myśli plan, abyś zrozumiał, zamiast siadać przy klawiaturze i walić. Oto moje szacunki dotyczące cyklu życia projektu, wszystkie liczby +/- 5%. Przede wszystkim (wymagania i przypadki użycia, architektura, szczegółowy projekt) 50%, kodowanie 10 do 15%, testowanie, reszta. „Jeśli nie uda ci się zaplanować, nie uda ci się”
Mawg
6

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.

BillThor
źródło
1
Ważnym punktem tutaj nie było stwierdzenie, ile trzeba wiedzieć o kodzie, aby dokonać zmiany. Oczywiście będzie to zależeć od wielu rzeczy, ale nigdy nie będziesz musiał rozumieć całego kodu, ani przegląd nie zapewni tego zrozumienia, ale nawet aby znaleźć linię kodu, którą zmienisz, potrzebujesz pewnej wiedzy na temat ogólna struktura projektu.
fiatjaf
+1 Nie ma nic specjalnego w open source. Przez ponad 10 lat doświadczenia w pracy w branży nigdy nie widziałem dokumentu przeglądowego. Zazwyczaj pracodawcy oczekują, że pierwszy miesiąc zatrudnienia będzie zerowy, ponieważ studiujesz bazę kodów. „Przeglądy” są zwykle realizowane jako zadawanie pytań współpracownikom
slebetman
5

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).

bjmc
źródło
brzmi to bardziej jak komentarz, patrz Jak odpowiedzieć
komara
4
Twój komentarz nie jest konstruktywny. Czego konkretnie brakuje? Wiele innych odpowiedzi tutaj jest długimi spekulacjami na temat możliwych powodów, dla których programiści mogą nie pisać dokumentacji przeglądowej. Odsyłam do konkretnego przykładu dobrych dokumentów przeglądowych.
bjmc
1
Wydaje mi się, że brakuje odpowiedzi na zadane pytanie: „Dlaczego nie ma przeglądów kodu dla projektów typu open source?”
komara
3
Uważam, że nie jest możliwe, aby dokładnie odpowiedzieć na pytanie, jak napisane, podczas gdy w rzeczywistości nie przeglądy kodu dla niektórych projektów open-source. Zredagowałem swoją odpowiedź, aby wyjaśnić, że wąsko odpowiadam na prośbę o przykłady, które użytkownik mógł pominąć.
bjmc
1
Pytanie w formie pisemnej brzmi: „Czy są takie rzeczy i brakuje mi ich?” Ta odpowiedź definitywnie wskazuje na istniejącą kolekcję takich przeglądów kodu. Dlatego uważam, że jest to świetna (i odpowiednia) odpowiedź na pytanie.
Jim Garrison,
4

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.

Jak
źródło
+1 „dokumentacja może zająć tyle czasu, ile napisanie kodu w pierwszej kolejności” - lub dłużej!
Marco,
-1

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ń.

BЈовић
źródło
8
Bez względu na to, ile przykładów można wymienić w przypadku źle udokumentowanych projektów open source, moim zdaniem twierdzenie, że „celowo okaleczają swoją dokumentację” musi być poparte przekonującymi dowodami (i nawet wtedy prawdopodobnie nie jest to Ogólne zestawienie).
LUB Mapper
@ORMapper Zacznijmy od „Bluez - największej tajemnicy linux” . Jako jedyna biblioteka bluetooth dla systemu Linux trudno mi uwierzyć, że nie jest to dokumentacja, ponieważ jest to dodatkowy wysiłek. Do diabła, jest doxygen i jak ciężko jest pisać proste samouczki?
BЈовић
@ORMapper Następnie jest jądro Linux. Jeśli czegoś brakuje (np. Sterownika jądra), jeśli Twoja firma nie ma doświadczenia, możesz albo kogoś zatrudnić, albo znaleźć freelancera lub firmę, która zrobi to za Ciebie. Jest to więc oprogramowanie typu open source, ale ma swoją cenę
BЈовић
@ORMapper Następnie jest projekt open source z dokumentacją w formie papierowej. Więc kupujesz książkę i nie ma innej dokumentacji. Czy ta dokumentacja jest paraliżująca, czy nie?
BЈовић
2
Za to, co jest warte, widziałem wystarczająco zyskujących z tandetnej dokumentacji, aby przynajmniej zastanawiać się, czy jest to celowe. Kiedy te same grupy, które umieszczają w Internecie częściowo ocenianą dokumentację, chętnie sprzedają ci książkę lub klasę szkoleniową, wcale nie potrzeba dużo cynizmu, aby dojść do takiego wniosku.
cHao