W jaki sposób projekty typu open source mogą odnieść sukces bez dokumentacji dotyczącej ich projektu lub architektury?

11

Chcę poprawić swoje umiejętności programistyczne, studiując znane projekty open source, ale łatwo się zgubić, po prostu wskakując do ich kodu źródłowego.

Postanowiłem więc przeczytać ich dokumentację dotyczącą ich projektu lub architektury (np. Diagramów UML), aby najpierw uzyskać ogólne wyobrażenie o organizacji ich kodu. Ku mojemu zaskoczeniu nie mogę jednak znaleźć żadnej dokumentacji architektonicznej dla dużych projektów open source, takich jak Hibernate, Spring, ASP.NET MVC, Rails itp.

Zacząłem się zastanawiać: w jaki sposób projekt typu open source może odnieść sukces, jeśli nowi twórcy nie mają dokumentacji architektonicznej / projektowej do przeczytania, lub jeśli kierownik projektu właśnie otworzył kod źródłowy, ale zamknął dokumentację?

TomCaps
źródło
3
"większość"? Czy możesz to poprzeć konkretnymi statystykami? Ile przeczytałeś? Ile tu tego jest? Ilu brakowało odpowiedniej dokumentacji? Jeśli nie masz liczb, usuń słowa „większość” i zastąp je prawdziwymi faktami na podstawie tego, co naprawdę znalazłeś. Również odnosząc się do siebie, proszę wpisać wielkie „I”.
S.Lott,
@ S.Lott Przepraszamy za subiektywne „najbardziej”. Jestem nowicjuszem w branży oprogramowania. Próbuję wyszukiwać dokumenty, o których słyszałem podczas studiów (takie jak Diagram UML, Schemat blokowy, Krótki dokument projektowy, Detaled Design Doc itp.) Dla wymienionych projektów zarówno na stronie internetowej projektu, jak i w repozytorium kodów, ale bez powodzenia, tylko po to, aby znaleźć dokumentację instrukcji obsługi. Czy możesz nauczyć mnie jakiegoś powszechnego sposobu przeszukiwania dokumentów desgin / archiecture?
TomCaps
1
Usuń „Wiele”. To jest tak samo niepoprawne jak większość. Proszę zaktualizować pytanie konkretnie listy konkretnych projektów open source, które specyficznie brakuje dokumentacji konkretnego chcesz zobaczyć. Proszę być dokładnym i konkretnym. Proszę nie bądź subiektywny i niejasny.
S.Lott,
Podejrzewam, że powodem, dla którego ASP.NET MVC nie zawiera diagramów UML, jest to, że Visual Studio może je utworzyć z kodu źródłowego.
user16764
5
Działasz przy fałszywym założeniu, że „przedsiębiorczość” to dobra rzecz. Wszystko, czego nauczyłeś się na studiach o projektowaniu, to kłamstwa: UML nie ma absolutnie żadnej wartości. Podczas tworzenia projektu potrzebujesz jedynie ogólnego wyobrażenia o tym, co powinien zrobić, i chęci wyrzucenia go, jeśli zrobisz to źle za pierwszym razem. W przypadku istniejącego projektu zwykle wystarczy przejrzeć główny nagłówek, aby uzyskać dobry pomysł na temat układu projektu.
o11c

Odpowiedzi:

10

dlaczego projekt open source może odnieść sukces, jeśli nowoprzybyły programista nie ma dokumentu architektonicznego / projektowego do przeczytania?

Zakładamy niezmiennie, że wiesz, co robisz, i masz dość intymne zrozumienie tego, co zamierzasz (i oczekujesz) zobaczyć.

Na przykład, jeśli spojrzysz na kod PHP frameworka Symfony, powinieneś już wiedzieć o wstrzykiwaniu zależności, zdarzeniach, wzorcu model / widok / kontroler i tak dalej.

Podobnie, jeśli zagłębisz się w kod C jądra linuksa, założymy, że będziesz realistycznie kompetentny w zakresie modułowości, sygnałów, procesów, wątków i co nie. Oczekuje się także, że będziesz miał talent do jedzenia w systemie szesnastkowym przez cały dzień i do kopania rdzeni za pomocą ogromnej łopaty.

Opiekunowie nie będą mieli problemów z dokumentowaniem architektury, ponieważ jest to rzeczowa kwestia. Czasami znajdziesz zarys tego, co leży w drzewie źródłowym. Częściej jednak sposób uporządkowania drzewa źródłowego sprawia, że ​​wszystko jest zrozumiałe.

Krótko mówiąc, jeśli brakuje ci umiejętności, których opiekunowie oczekują od ciebie, zanim zajrzysz do ich kodu, prawdopodobnie przekopujesz rzeczy, które znacznie przekraczają twoją ocenę płacową. Najpierw zapoznaj się z koncepcjami - Co to jest model MVC? Co to jest wstrzyknięcie zależności? Itd. Następnie zanurkuj.

Denis de Bernardy
źródło
1
Chociaż jeśli spojrzysz na listy mailingowe, jądro Linuksa prowadzi szeroko zakrojoną dyskusję na temat architektury, gdy tylko ktoś ma problem lub chce coś zmienić. Napisano o tym także sporo dokumentów - choć nie w samym drzewie źródeł jądra.
edA-qa mort-ora-y
17

Najbardziej udane projekty open source odniosły sukces, ponieważ przede wszystkim program był imponujący lub zrobił coś, czego żaden inny program w tym czasie nie był w stanie zrobić. Nie musi to oznaczać, że źródło jest dobrze udokumentowane, ponieważ programiści, którzy rozpoczęli projekt od początku, znają kod wystarczająco dobrze, aby go nie potrzebować. To niefortunna rzeczywistość, że projekty open source nie muszą być dobrze udokumentowane. Musi to być dobry program lub mierny program, ale dobrze udokumentowany, aby programiści mogli się nim zainteresować.

Neil
źródło
W mojej firmie jest to procedura wymagająca, że ​​programiści muszą dostarczyć Szczegółowy Dokument Projektowy przed zatwierdzeniem napisać dowolny kod na projekcie. Czy ta procedura jest nieprawidłowa w przypadku projektu typu open source?
TomCaps
5
@TomCaps Myślę, że głównym powodem, że tak mało projektów FOSS posiada obszerną dokumentację jest dość prosta: jeśli pisanie mały program do rozwiązywania potrzebę, że ty masz, to jest prawdopodobne, że od czasu dewelopera, że nie trzeba również dokumentację, ty będą chcieli spędzać czas na ulepszaniu programu, a nie na pisaniu dokumentacji, która nie jest dla nikogo przydatna (a jeśli projekt nigdy nie będzie używany przez nikogo poza deweloperem?). Nie jest to najlepsza praktyka, ale wiele projektów FOSS ma mało czasu programisty.
Jeff Welling
5
@TomCaps: Ta procedura jest nienormalna dla większości firm, które znam ...
Treb
1
Większość projektów typu open source to nie firmy. Zastanawiasz się, co się stanie, gdy dostanę projekt, za który otrzymuję wynagrodzenie, z terminem i budżetem. Jeśli masz grupę ludzi kodujących, by zaspokoić ich potrzeby lub dla zabawy i nie ma budżetu ani klienta, nie masz tego typu rzeczy.
Elin
1
@TomCaps - każdy, kto pisze oprogramowanie Open Source, może robić dokładnie to, co lubi. Niektóre projekty (np. Rodzina Apache) mają zasady i wytyczne dla każdego, kto popełnia kod, a czasami obejmuje to standardy dublowania itp. Również kwestionowałbym wartość „szczegółowego dokumentu projektowego”, ponieważ niezmiennie zablokuje to fizyczny projekt, który (w moje osobiste doświadczenie) jest zwykle nieoptymalne. Szczegółowy opis „tego, co” ma zrobić program, pozwala programistom na optymalizację wdrożenia i zastosowanie kreatywnych strategii do rozwiązania.
James Anderson
12

Ponieważ programiści Open Source są zwykle utalentowani i wybierają również projekty w swojej dziedzinie wiedzy, mają już w swoich głowach „dokumentację”. Przy niewielkiej przesadzie dokładna dokumentacja jest potrzebna tylko w przypadku braku któregoś z nich: o)

Szczerze mówiąc, tak naprawdę nie czytam „dokumentacji” w obliczu nieznanej bazy kodu. Szybkie wprowadzenie, może kilka szkiców koncepcyjnych i od razu do kodu! Eksperymentuj, wypróbuj małe zmiany. Działa idealnie dla dobrze zaprojektowanego kodu. Jeśli mam do czynienia z okropnym bałaganem, najlepszym sposobem na ich nauczenie jest stopniowe refaktoryzacja w celu poprawy przejrzystości (najlepiej przy pomocy testów jednostkowych).

Dodatkowym powodem mogą być zwykłe organiczne korzenie tych projektów. Architektura jest więc raczej ewolucją wizji w umysłach programistów niż stwierdzoną „udokumentowaną” istotą.

Zniszczyć
źródło
8

Powód, dla którego takie dokumenty często nie istnieją, jest dość prosty: programiści lubią programować, a nie pisać dokumentację. Zwłaszcza w przypadku projektów typu open source, które programiści często uczestniczą w czasie wolnym / wolnym.

Zasadniczo pisanie dokumentacji nie jest zabawne. A jeśli nie dostają za to zapłaty, kto chce spędzać wolny czas na robieniu czegoś, co nie jest zabawne?

Grandmaster B.
źródło
Niektóre duże projekty open source (GCC, jądro Linuksa, Firefox, Qt, ....) mają większość (lub znaczną część) swoich współpracowników opłaconą do pracy (pełny lub pół etatu) nad projektem. Więc nawet po opłaceniu bezpłatnego oprogramowania nie piszą dużej ilości dokumentacji
Basile Starynkevitch