O co chodzi z niechęcią do dokumentacji w branży?

47

Wydaje się, że istnieje awersja do pisania nawet najbardziej podstawowej dokumentacji. Nasze projekty README są stosunkowo puste. Dokumenty nie zawierają nawet zaktualizowanych list zależności.

Czy jest coś, czego nie znam w branży, co sprawia, że ​​programiści nie lubią pisać dokumentacji? W razie potrzeby mogę pisać akapity dokumentów, więc dlaczego inni są temu przeciwni?

Co ważniejsze, jak ich przekonać, że pisanie dokumentów pozwoli nam zaoszczędzić czas i frustrację w przyszłości?

Rudolf Olah
źródło
13
Ponieważ wiemy, co robimy! Dlaczego mielibyśmy tracić czas na zapisywanie tego, co już wiemy i nigdy nie zapomnimy!?!? Poważnie, mam do czynienia z tym samym na co dzień, pracując na bazie kodu, która rozpoczęła proces projektowania 7 lat temu i była codziennie aktualizowana przez zespół złożony z 4-7 inżynierów. Dokumentacja jest czymś, z czym zawsze się zmagaliśmy, ale jest złem koniecznym.
Ampt
61
Ponieważ doświadczenie udowodniło, że nikt nie czyta dokumentów.
user16764
7
Z biznesowego punktu widzenia stosy dokumentacji kosztują pieniądze firmy tu i teraz, kiedy można zamiast tego pracować nad kolejnym projektem, aby zarabiać pieniądze. Tą potrzebą, aby zawsze przynosić zysk, jest presja, jaką odczuwasz wobec „marnowania czasu” na pisanie dokumentacji. Ponadto nikt nigdy nie czyta dokumentów i zamiast tego czyta źródła, ponieważ tylko one są ostatecznym autorytetem.
Patrick Hughes,
14
Utrzymywanie synchronizacji dokumentów z najnowszym kodem może być „trudne”, jeśli piszesz na wyższym poziomie niż Javadoc lub równoważny.
Dan Pichelman,
12
To nie jest zabawne ...

Odpowiedzi:

21

Nie sądzę, że warto spekulować na temat motywacji ludzi, którzy nie przyjmują czegoś, co uważasz za dobrą praktykę, lub którzy nadal robią coś, co uważasz za złą praktykę. W tym biznesie osoby należące do jednej lub obu tych kategorii znacznie przewyższą liczbę osób, z którymi spotkasz się oko w oko, więc przestań się szaleć.

Zamiast tego skup się na problemie i możliwych rozwiązaniach.

1. Napisz własną dobrą dokumentację

Może nie być realistyczne oczekiwanie, że wszyscy w zespole skierują swoje wysiłki na rzeczy, które postrzegasz jako problem. Jest to szczególnie ważne, jeśli jesteś względnie nowym członkiem zespołu. Zgaduję, że tak, bo gdybyś był członkiem założycielem zespołu, wydaje się całkiem prawdopodobne, że już wcześniej rozwiązałeś ten problem.

Zamiast tego zastanów się, czy nie dążyć do tego, aby samodzielnie napisać dobrą dokumentację i zachęcić ludzi do korzystania z niej. Na przykład, jeśli ktoś z mojego zespołu zapyta mnie, gdzie jest kod źródłowy Projektu A lub jakiej specjalnej konfiguracji potrzebuje Projekt A, wskazuję mu stronę wiki Projektu A.

Jeśli ktoś zapyta mnie, jak napisać nową implementację fabryki F, aby dostosować coś do klienta C, odpowiadam, że jest to na stronie 10 przewodnika dla programistów.

Większość programistów nie znosi zadawania pytań, które mogłyby sprawić, że wyglądałyby tak, jakby nie mogły „czytać kodu” nawet bardziej niż nienawidzą czytać dokumentacji, więc po wystarczającej liczbie odpowiedzi tego rodzaju, najpierw przejdą do dokumentów.

2. Udowodnij wartość swojej dokumentacji

Upewnij się, że wykorzystujesz każdą okazję, aby wskazać, gdzie dokumentacja potwierdza swoją wartość (lub miałaby, gdyby była używana). Staraj się być subtelny i unikaj „powiedziałem ci tak”, ale mówienie czegoś takiego jest całkowicie uzasadnione

Na przyszłość strona wiki tego projektu zawiera informacje o gałęzi kodu podstawowego, który został utworzony w celu zapewnienia ciągłej obsługi wersji 2.1, więc w przyszłości możemy uniknąć konieczności wykonywania pełnego testu regresji, jeśli sprawdzą osoby, które utrzymują wydane wersje wiki przed sprawdzeniem kodu.

lub

Tak się cieszę, że zapisałem kroki do wykonania Zadania T. Nie obchodzi mnie to, czy nikt inny go nie użyje - już zaoszczędziłem więcej czasu niż to, co napisałem.

3. Uzyskaj zarząd na pokładzie

Po kilku zdarzeniach, w których posiadanie dokumentacji pozwala zaoszczędzić czas i pieniądze, prawdopodobnie zauważysz wyraźną „odwilż” w kierunku dokumentacji. To jest czas na podkreślenie tego, zaczynając uwzględniać czas na dokumentację w swoich szacunkach (chociaż szczerze mówiąc, zwykle aktualizuję / tworzę dokumenty podczas uruchomionych długich procesów, takich jak kompilacje lub zameldowania). Zwłaszcza, jeśli jest to ostatni wynajem, możliwe, że nie zostanie to zakwestionowane, ale zamiast tego będzie postrzegane jako nowa praktyka, którą przyprowadzasz z poprzedniego miejsca pracy (co może być).

Słowo ostrzeżenia: większość szefów nie lubi zmuszać ludzi do robienia czegokolwiek, szczególnie rzeczy niezwiązanych bezpośrednio z rozliczalnym zadaniem, więc nie oczekuj, że to wsparcie będzie miało formę mandatu. Zamiast tego jest bardziej prawdopodobne, że będziesz mógł stosunkowo swobodnie pisać więcej dokumentów.

4. Zachęcaj do dokumentacji, gdy ją zobaczysz

Być może jednym z powodów, dla których ludzie nie piszą dokumentów tak często, jak powinni, jest to, że czują, że nikt ich nie czyta. Więc kiedy zobaczysz coś, co lubisz, pamiętaj, aby przynajmniej wspomnieć, że byłeś zadowolony, że jest dostępny.

Jeśli Twój zespół dokonuje recenzji kodu, jest to czas, w którym możesz wpisać subtelne słowo lub dwa, aby zachęcić do dobrych komentarzy.

Dziękuję za udokumentowanie obejścia błędu B w Framework G. Nie wiedziałem o tym i nie sądzę, żebym mógł zrozumieć, co robiłeś bez tego.

Jeśli masz kogoś w zespole, który jest naprawdę entuzjastycznie nastawiony do dokumentacji, nie szkodzi kultywowaniu tej osoby przez pójście na lunch lub kawę i upewnienie się, że zaoferujesz trochę potwierdzenia, aby przeciwdziałać zniechęceniu, jakie mogą uzyskać od reszty zespołu nie docenia dokumentacji tak bardzo.

Poza tym to naprawdę nie jest twój problem, chyba że zajmujesz stanowisko kierownicze lub kierownicze. Możesz doprowadzić konia do wody, ale nie możesz go pić. Jeśli to nie jest twój koń, możesz nie być szczęśliwy, że jest spragniony, ale wszystko, co możesz zrobić, to wypełnić koryto.

Amy Blankenship
źródło
1
+1 za punkt # 2, bezpośrednio odpowiadając na pytanie PO, które zaczyna się od „Jak przekonać ...”
Ray Toal
Podoba mi się ta odpowiedź, inne skupiły się bardziej na „dlaczego” zamiast na „jak”
Rudolf Olah,
@omouse - to dlatego, że w większości przypadków pisanie dokumentacji nie oszczędza czasu i frustracji w przyszłości. Rzadko są one dokładne i ludzie nigdy ich nie czytają, nawet gdy są.
Telastyn
1
SOLIDNE zasady zwykle nie oszczędzają czasu ani nie skutkują lepszym projektem, ponieważ większość ludzi albo ich w pełni nie rozumie, albo naprawdę nie dba o to. Zgodnie z Twoją logiką nie powinniśmy dążyć do ich zastosowania, GRASP ani innych dobrych praktyk. Przypomnij mi, dlaczego ponownie zawracasz sobie głowę uczestnictwem w programistach?
Amy Blankenship,
Uważa, że ​​bardzo pomocne jest spekulowanie na temat motywacji ludzi.
tymtam,
55

Są dwa główne czynniki w moim doświadczeniu:

Terminy

Większość firm jest tak nastawiona na datę, że kontrola jakości, zadłużenie technologiczne i faktyczny projekt zostały obcięte, aby kierownik projektu nie wyglądał źle lub nie dotarł do absurdalnego, nadmiernie obiecanego terminu klienta. W środowisku, w którym nawet funkcjonalna jakość jest obniżona, długoterminowa inwestycja, taka jak dokumentacja, ma niewielkie szanse.

Zmiana

Stosunkowo nową najlepszą praktyką dla programistów jest odznaczanie komentarzy. Chodzi o to, że przechowywanie informacji w dwóch miejscach (kod [łącznie z testami] i komentarze wokół kodu) prowadzi do dużych kosztów ogólnych w utrzymywaniu ich w synchronizacji z niewielką korzyścią. „Jeśli twój kod jest tak trudny do odczytania, że ​​potrzebujesz komentarzy, czy nie lepiej byłoby poświęcić czas na jego wyczyszczenie?”

Osobiście nie będę nawet patrzeć na komentarze. Kod nie może kłamać.

Dokumentacja podąża tą samą drogą. Dzięki powszechnemu stosowaniu zwinności ludzie potwierdzają, że wymagania zmieniają się regularnie. Przy powszechnym stosowaniu refaktoryzacji organizacja kodu zmieni się dość znacząco. Po co spędzać czas na dokumentowaniu wszystkich rzeczy, które na pewno się zmienią? Kod i testy powinny wykonywać wystarczająco dobrą robotę.

Telastyn
źródło
11
+1 za „Osobiście nawet nie patrzę na komentarze”, myślę, że jest to powszechne; kiedy dorośniesz do pewnego poziomu komfortu z samego kodu, można go czytać szybciej niż komentarzach (i jeszcze szybciej, jeśli komentarze nie są w drodze), a kod nie kłamie
Jimmy Hoffa
40
Pomija to punkt komentarzy, który wyjaśnia, dlaczego . Nie muszą być wszędzie i nie muszą być bardzo długie, ale dobrze umieszczony link do reguł biznesowych opisujących, dlaczego kolejne 20 linii naprawdę dziwnej logiki istnieje w obecnym stanie, jest znacznie więcej wygodne niż przeszukiwanie historii wersji w celu znalezienia oryginalnego uzasadnienia.
zzzzBov
7
@zzzzBov - absolutnie taki jest współczesny pogląd na rzeczy. Zmieniło się to w porównaniu z poprzednimi punktami widzenia, które zachęcały do ​​bardziej wszechstronnego komentowania. Podobnie dokumentacja tego, co robi kod, zmniejszyła się do dokumentacji, która skupia się na tym, dlaczego to robi (na przykład dokumenty projektowe).
Telastyn,
8
Kod może kłamać. Klient mógł chcieć czegoś i zostało to zakodowane, aby zrobić coś innego. Więc jeśli teraz masz tylko kod, to prawda?
Czwartek Czwartek
6
Kod może kłamać ... Mam metodę na 4000 linii (hej, nie utworzyłem go, teraz jestem jego właścicielem ...) i widzę kolekcję o wyraźnej nazwie „productList”, więc dla nowej zmiany dodaję produkt sprzeciwić się temu. Wspaniały. Tylko, że to nie działa, okazuje się, że jakiś poprzedni programista był „wydajny” i ponownie używał zmiennej typu List, aby uniknąć zaśmiecania 4000 wierszy zbyt dużą liczbą zmiennych, aw tym zakresie zawiera obiekty Klienta ...
Kevin Rubin
16

W grę wchodzi wiele czynników:

  1. Dobrze napisany kod jest własną dokumentacją. Wszystkie pozostałe rzeczy są jednakowe, lepiej jest napisać wyraźniejszy kod, który mówi sam za siebie, niż więcej dokumentacji. Zrób to, a będziesz musiał zmodyfikować mniej dokumentacji podczas zmiany tego kodu.

  2. Pisanie dokumentacji jest prawdopodobnie inną umiejętnością niż pisanie kodu. Niektórzy programiści są w tym lepsi niż inni. Niektóre są znacznie lepsze w pisaniu kodu niż w pisaniu dokumentacji.

  3. Dokumentacja powinna być napisana tylko raz , a nie dwa razy (raz w kodzie źródłowym i ponownie w przewodniku programisty). Dlatego mamy takie rzeczy, jak komentarze XML i generatory dokumentacji. Niestety korzystanie z takich narzędzi może być trudniejsze i bardziej kłopotliwe niż pisanie dokumentacji ręcznie, dlatego nie widzisz tych narzędzi powszechnie używanych.

  4. Dobra dokumentacja jest czasochłonna i trudna do zrobienia. Wszystkie inne rzeczy są jednakowe, pisanie nowego kodu może mieć większą wartość niż pisanie dokumentacji dla już istniejącego kodu.

  5. Kiedy kod się zmienia, musisz również zmienić dokumentację. Im mniej dokumentacji, tym mniej trzeba zmienić.

  6. Zresztą nikt nie czyta dokumentacji, więc po co się tym przejmować?

Robert Harvey
źródło
2
jeśli chodzi o nr 1, nie sądzę, żeby tak było zawsze, ale nr 4 jest zdecydowanie prawdą
Rudolf Olah,
3
@whatsisname: Wcale nie. Napisz wyraźniejszy kod, który wymaga mniej dokumentacji, a będziesz musiał zmodyfikować mniej dokumentacji po zmianie tego kodu.
Robert Harvey,
2
@th Czwarteksgeek: Co oznacza te kule, to że nie powinieneś pisać dokumentacji dwa razy: raz dla komentarzy do kodu i ponownie dla odniesienia do pliku pomocy / programisty. Z pewnością nie powinieneś go przepisywać dwa razy. Czy czytacie to?
Robert Harvey,
4
# 6 ... Myślę, że jest to powszechne nieporozumienie. Dużo ludzi czytać dokumentację dokładnie.
Dynamiczny
3
@tymek: Masz swój znak do tyłu. Ludzie, to nie jest samouczek na temat tworzenia dokumentacji; jest to ocena tego, dlaczego programiści mają do tego negatywne podejście.
Robert Harvey
11

Słoń w pokoju: programiści nie są (niekoniecznie) pisarzami. Nie muszą też koniecznie przekazywać swoich wdrożeń pisarzom technicznym. Drugi słoń w pokoju: autorzy techniczni zazwyczaj nie są w stanie opracować szczegółów przydatnych przyszłym programistom (nawet jeśli programiści raczyliby im to wyjaśnić).

Złożony system może z czasem stać się nieprzenikniony bez odpowiedniej dokumentacji. Kod staje się mniej wartościowy odwrotnie proporcjonalnie do jego sprawdzalności [sic]. Rozwiązany zarząd wynajmuje Inżyniera oprogramowania, który może odczytać kod i dane koncentryczne od programistów, płaci mu według stawki programisty i upoważnia go do dokumentowania i prowadzenia dokumentacji. Ten pisarz może odczytać kod i będzie wiedział, jakie pytania zadać, i w razie potrzeby poda szczegółowe informacje. Podobnie jak masz dział kontroli jakości, masz dział dokumentacji wewnętrznej.

Kod stanie się bardziej wartościowy, ponieważ możesz licencjonować go stronom trzecim (ponieważ on może go zrozumieć), kod można łatwiej poddać audytowi i ulepszyć / przefaktoryzować, będziesz mógł lepiej wykorzystać kod nawet tam, gdzie możesz to łatwo uwzględnij bardziej lekkie wersje swojego oprogramowania, a będziesz mógł łatwiej wprowadzać nowych programistów do projektu, inżynierowie wsparcia pokochają pracę dla Ciebie.

To się nigdy nie wydarzy.

naftalimich
źródło
1
Nie wspominając już o tym, że próbując opisać istniejący kod, trudniej jest podać dobry opis, gdy kod i funkcjonalność są tak złożone, że nikt nie wie, co robi, więc wszelkie nowe zmiany mają wpływ, którego nowy programista nie zrobił wiedzieć o ...
Kevin Rubin
1
Sugerowałbym, że „podstawowa umiejętność komunikowania swoich zamiarów z (ograniczoną) dokumentacją” jest niezbędną umiejętnością programistyczną. Programista nie musi być poetą, ale jeśli nie potrafi dokumentować, szczerze mówiąc, nie chcę go w moim zespole. Taka osoba jest długoterminową odpowiedzialnością.
5

Co ważniejsze, jak ich przekonać, że pisanie dokumentów pozwoli nam zaoszczędzić czas i frustrację w przyszłości?

Czy to robi?

Istnieją dwa rodzaje dokumentacji:

Przydatna dokumentacja

Dokumentuje, jak korzystać z gotowego produktu, interfejsu API, jakie adresy IP lub nazwy adresów URL mają nasze serwery itp. Zasadniczo wszystko, co jest intensywnie używane na co dzień. Błędne informacje zostaną szybko znalezione i zostaną poprawione. Musi być znaleziony łatwy i łatwy do edycji (np. Online Wiki).

Bezużyteczna dokumentacja

Dokumentacja, która często się zmienia, bardzo mało osób jest nią zainteresowanych i nikt nie wie, gdzie ją znaleźć. Podobnie jak obecny stan wdrażanej funkcji. Lub dokumenty wymagań w dokumencie Word ukrytym gdzieś w SVN, zaktualizowanym 3 lata temu. Napisanie tej dokumentacji zajmie trochę czasu, a później okaże się, że jest błędna. Nie możesz polegać na tego rodzaju dokumentacji. To jest bezużyteczne. To marnuje czas.

Programiści nie lubią pisać ani czytać bezużytecznej dokumentacji. Ale jeśli możesz pokazać im dokumentację, która jest przydatna, napiszą ją. Odnieśliśmy spore sukcesy w moim ostatnim projekcie, gdy wprowadziliśmy Wiki, w której moglibyśmy często wpisywać wszystkie potrzebne informacje.

Uooo
źródło
4

Powiedziałbym, że głównym powodem jest brak woli i niezrozumienie funkcji dokumentacji. Należy wziąć pod uwagę szereg klas dokumentacji:

Dokumentacja produktu / wydania

To wszystko, co pasuje do Twojego „gotowego” produktu. To nie tylko podręczniki, to CZYTNIKI, dzienniki zmian, instrukcje i tym podobne. Teoretycznie można uniknąć pisania ich, ale w efekcie powstaje produkt, którego ludzie nie chcą używać, lub obciążenie, które jest niepotrzebnie drogie.

Dokumentacja API

To opisuje coś, co powinno być względnie statyczne. Ponieważ wielu konsumentów może kodować do twojego API, powinien być wystarczająco stabilny, aby niektóre prozy opisujące jak go używać miały wartość. Opisanie obsługiwanych parametrów, wartości zwracanej i błędów, które mogą zostać zgłoszone, pozwoli innym użytkownikom zrozumieć interfejs API na odpowiednim poziomie abstrakcji - interfejs ( nie implementacja).

Komentarze do kodu

Wydaje się, że w tej chwili zmienia się opinia branży na temat komentarzy. Kiedy zacząłem profesjonalnie kodować, komentarze były niezbędnym warunkiem pisania kodu. Teraz moda polega na pisaniu tak przejrzystego kodu, że komentarze nie są konieczne. Zaryzykuję przypuszczenie, że jest to częściowo spowodowane faktem, że wiele współczesnych języków jest pisanych na znacznie wyższym poziomie i łatwiej jest napisać czytelny kod w Javie, JavaScript, Ruby itp. Niż w asemblerze , C, FORTRAN itp. Tak więc komentarze miały znacznie większą wartość.

Nadal uważam, że w komentarzach opisujących intencję sekcji kodu znajduje się wartość lub kilka szczegółów na temat tego, dlaczego określony algorytm został wybrany zamiast bardziej oczywistego (aby uniknąć nadgorliwych refaktoryzujących potworów z „naprawiania” kodu, który nie ” faktycznie trzeba to naprawić).

Niestety, w decyzjach programistów o nieudokumentowaniu jest wiele samolubstwa, racjonalizacji i złudzeń. Rzeczywistość jest taka, że ​​podobnie jak kod, podstawowymi odbiorcami dokumentacji są inni ludzie. Tak więc decyzje o napisaniu (lub nie napisaniu) dokumentacji na dowolnym poziomie należy podjąć na poziomie zespołu. W przypadku wyższych poziomów abstrakcji sensowniejsze może być posiadanie kogoś innego niż programistów. Jeśli chodzi o dokumentację na poziomie komentarzy, osiągnięcie porozumienia w sprawie celu i intencji komentarzy powinno być uzgodnione wspólnie, szczególnie w zespołach o mieszanych umiejętnościach i doświadczeniu. Nie jest dobrze mieć starszych programistów piszących kod, do którego młodsi programiści nie mogą podejść. Pewna dobrze umiejscowiona i dobrze napisana dokumentacja może pozwolić zespołowi działać znacznie efektywniej

Dancrumb
źródło
1
+1 za „główną grupą docelową dokumentacji są inne osoby”. Zbyt wielu programistów tak naprawdę nie docenia komunikacji z innymi. (Dlatego też trudno będzie im osiągnąć wyższy poziom starszeństwa).
Donal Fellows
4

Oto moje dwa centy.

  1. Manifest Agile stwierdza „Działające oprogramowanie w oparciu o obszerną dokumentację” i nie wszyscy czytają dalej, aby dotrzeć do „Oznacza to, że chociaż elementy po prawej stronie mają wartość, bardziej cenimy te po lewej”.

  2. Niestety jest to powszechne w https://en.wikipedia.org/wiki/Code_and_fix i dokumentacja nie działa z tym modelem (synchronizuje się).

  3. Branża tworzenia oprogramowania nie jest dobrze regulowana. Nie ma prawnego wymogu pisania dokumentacji.

  4. Kod samodokumentujący to aktualny trend.

Powiedziawszy to, myślę, że jest tam dużo dobrej dokumentacji.

tymtam
źródło
(1) „ Bardziej cenimy rzeczy po lewej stronie ... ” nie oznacza, że ​​wcale nie dbamy o prawą stronę. (2) „ 4. Kod samodokumentujący to aktualny trend ”. Jeśli dokumentacja nie jest konieczna, to dlaczego ludzie narzekają przede wszystkim na złą / brakującą dokumentację? (3) Każdy programista, który potrzebuje informacji, oszczędza czas jednego programisty, który nie dokumentuje swojej pracy , ponieważ musi zeskanować 5000 wierszy samodokumentującego się kodu zamiast 5-stronicowej dokumentacji. Wydajność to coś innego, ale hej, jesteśmy zwinni!
JensG
2

Dokumentacja wymaga czasu i podejrzewam, że wielu programistów miało zbyt wiele wtyczek z dokumentacją, która była gorsza niż bezużyteczna. Wpadają na pomysł, że nie tylko dokumentowanie sprawi im kłopoty ze strony swojego menedżera (tego samego faceta, który ciągle wycina część harmonogramu kontroli jakości), ale nie pomoże to nikomu, łącznie z nimi.

Każda na wpół przyzwoita dokumentacja to inwestycja w przyszłość. Jeśli nie zależy ci na przyszłości (ponieważ nie myślisz poza kolejną wypłatą lub myślisz, że to nie będzie twój problem), to myśl o zrobieniu dokumentacji jest wyjątkowo bolesna.

Michael Kohne
źródło
2

Wiele innych odpowiedzi wskazuje na to, że istnieją co najmniej dwa rodzaje dokumentacji: jeden zestaw dla innych programistów i inny zestaw dla użytkowników końcowych. W zależności od środowiska może być potrzebna dodatkowa dokumentacja dla administratorów systemu, instalatorów i personelu działu pomocy technicznej. Każda grupa docelowa ma inne potrzeby i poziomy zrozumienia.

Rozważmy (stereo-) typowego programistę: jest programistą z wyboru. Wybrał karierę poza zasięgiem opinii publicznej i spędza długie godziny za klawiaturą komunikując się przede wszystkim ze sobą. Proces dokumentacji jest formą komunikacji, a zestaw umiejętności wymaganych do tworzenia dobrej dokumentacji jest przeciwny do umiejętności wymaganych do tworzenia dobrego kodu.

Dobry autor dokumentacji może komunikować się w wielu językach: języku użytkowników, języku zarządzania, języku personelu pomocniczego, języku programistów. Zadaniem autora dokumentacji jest zrozumienie, co komunikuje się programista i przetłumaczenie go na formę zrozumiałą dla wszystkich innych grup.

Gdy spodziewasz się, że koderzy rozwiną umiejętności niezbędne do tego, aby stać się dobrymi komunikatorami (pisemnymi lub innymi), ilość czasu poświęcanego na doskonalenie podstawowego zestawu umiejętności (kodowanie!) Zmniejsza się. Im dalej od strefy komfortu (koduje i komunikuje się z innymi programistami), tym więcej czasu i energii będzie potrzebnych, aby dobrze wykonać zadanie. Można zasadnie oczekiwać, że profesjonalny programista będzie chciał skupić się przede wszystkim na swoich kluczowych kompetencjach, kosztem wszystkich innych.

Z tego powodu dokumentację (z wyjątkiem komentarzy kodu wbudowanego) najlepiej pozostawić komunikatorom, a nie programistom.

George Cummins
źródło
4
O rany. Im więcej rzeczy nauczysz się robić dobrze, tym lepiej zdobędziesz umiejętność robienia rzeczy dobrze. Tak jak ludzie znający wiele języków programują lepiej niż ludzie znający tylko jeden (ponieważ znają więcej sposobów myślenia o problemie), możliwość pisania, a nawet wizualizacji graficznej daje więcej narzędzi do myślenia i rozwiązywania problemów. Umiejętności potrzebne do opisania tego, co się dzieje, są tymi samymi, których potrzebujesz, aby drażnić, co powinno się wydarzyć.
Amy Blankenship
1
Chcę, aby inni programiści byli lub zostali wykwalifikowanymi komunikatorami. Zdecydowana większość wykonywanego przez nas programowania (przynajmniej w oprogramowaniu biznesowym) nie wymaga absolutnie najwyższego zestawu zaawansowanych umiejętności kodowania. Wymaga to znacznie lepszych umiejętności komunikacji międzyludzkiej, aby przyszli programiści zrozumieli, co zostało napisane. Im lepiej programista może się komunikować, szczególnie ludziom, których nigdy nie spotkają, tym lepiej będą myśleć o nich na dłuższą metę, a nie sprytny kod.
Kevin Rubin
2

Czytanie kodu pokazuje, jak to działa. Nie może wyjaśnić, dlaczego : potrzebujesz komentarzy.

Czytanie kodu pokazuje nazwę metody i typy parametrów. Nie może wyjaśnić semantyki ani dokładnej intencji autora: potrzebujesz komentarzy.

Komentarze nie zastępują czytania kodu, lecz go dodają.

benlast
źródło
4
+1 za sentyment. Ale to nie jest odpowiedź na pytanie; wydajesz się odpowiadać na coś innego niż zadane pytanie.
bignose
2

Dokumentacja nie jest wykonywana tak jak kod. W rezultacie często nie ma skutecznych pętli informacji zwrotnej, aby zweryfikować, czy dokumentacja jest na miejscu i jest kompletna. Z tego samego powodu komentarze kodu mają tendencję do gnicia.

Donald Knuth promował programowanie literackie jako sposób na poprawę jakości oprogramowania, efektywne pisanie dokumentacji z kodem. Widziałem kilka projektów, które dość skutecznie wykorzystały to podejście.

Osobiście staram się trzymać nowoczesnego trendu utrzymywania publicznego interfejsu API twojego kodu tak, aby był jak najbardziej czytelny, a także używania testów jednostkowych do dokumentowania wykorzystania przez innych programistów. Myślę, że jest to część większego pomysłu posiadania interfejsu API w formie, którą można eksplorować i odkrywać. Myślę, że to podejście jest częścią tego, co HATEOAS stara się osiągnąć dzięki usługom internetowym.

aboy021
źródło
Aby usprawiedliwić mój wybór automatycznego generowania dokumentacji, wymyśliłem próbną formułę pokazującą, w jaki sposób bezwładność ludzka jest winowajcą wszelkiego rodzaju zgnilizny komentarzy. Rozwijając argument, odkryłem, że tworzenie metod zapewniających rzeczywiste korzyści dla programisty, takich jak częściowo zautomatyzowane generowanie diagramów na podstawie meta komentarzy w kodzie źródłowym, jest zwykle aktualizowane za każdym razem, gdy programista próbuje zrozumieć kod. BTW, najczęściej ten programista jest po prostu „przyszłym mną”.
wolfmanx
0

Drobna uwaga, ale wydaje się ważna w przypadku niektórych programistów, którzy piszą nieprzyzwoicie małą dokumentację: nie potrafią pisać. Jeśli masz jakieś przybliżenie systemu 10 palców, zwykle piszesz więcej dokumentacji tylko dlatego, że jest to łatwe. Ale jeśli utkniesz z polowaniem i dziobaniem, jesteś zagubiony. Gdybym był odpowiedzialny za zatrudnienie, sprawdziłbym to.

Hans-Peter Störr
źródło
0

Ludzie, którzy nie lubią czytać dokumentacji, nie lubią pisać dokumentacji. Wielu programistów zrobi wszystko, aby uniknąć dokładnego przeczytania dokumentu.

Nie skupiaj się na pisaniu, skup się na czytaniu. Kiedy programiści czytają dokumentację i przyswajają z niej rzeczy, zobaczą wartość i będą o wiele bardziej skłonni do pisania niektórych.

Joeri Sebrechts
źródło
-1

Kiedy rozpocząłem swoją obecną pracę i przejąłem projekt sprzętu + oprogramowania od osób, które wcześniej nad nim pracowały, dostałem dokument zawierający około stu stronicowych słów opisujący system. Produkcja musiała zająć kilka dni. Spojrzałem na to może dwa razy. Mimo ogromnej ilości informacji rzadko odpowiadał na rzeczywiste pytania, jakie miałem na temat systemu, a nawet gdy tak było, szybsze było spojrzenie na kod.

Po wystarczającej ilości takich doświadczeń zaczynasz zastanawiać się, po co zawracać sobie głowę? Po co spędzać czas na odpowiadaniu na pytania, których ludzie nigdy nie zadawali? Zaczynasz zdawać sobie sprawę, jak naprawdę trudno jest przewidzieć, jakich informacji ludzie będą szukać w dokumentacji; jest nieuchronnie wypełniona faktami, które okazują się bezużyteczne, niejasne lub oczywiste, i brakuje im odpowiedzi na najbardziej palące pytania. Pamiętaj, że tworzenie użytecznej dokumentacji jest wysiłkiem w przewidywaniu ludzkich zachowań. Tak jak mało prawdopodobne jest, że projekt interfejsu użytkownika odniesie sukces, zanim przejdzie wiele iteracji testowania i debugowania, tak naiwnie jest myśleć, że można napisać użyteczną dokumentację opartą tylko na oczekiwaniach dotyczących interpretacji systemu przez ludzi i tego, co rolę, jaką odgrywa dokumentacja i jej język w tej interpretacji.

Wydaje mi się, że większość presji na pisanie dokumentacji wynika z faktu, że jest to nieprzyjemny obowiązek i ludzie lubią się wzajemnie winić, wykonując nieprzyjemne prace domowe („Nie zjadłeś swojego filboida!”).

JEDNAK

Nie sądzę, aby dokumentacja była pod każdym względem beznadziejna. Myślę, że jest to beznadziejne przede wszystkim, gdy ludzie patrzą na dokumentację jako dodatkowe obciążenie, które musi zostać spełnione przed zakończeniem pracy, jako ostatnia odrobina prac porządkowych, które należy przyspieszyć, i jako pole do sprawdzenia. Dokumentacja jest czymś, co powinieneś przeanalizować w aspektach swojego dnia, które zawsze robisz. Myślę, że e-mail jest szczególnie dobrym sposobem na tworzenie dokumentacji. Po dodaniu nowej funkcji napisz kilku osobom szybki e-mail z informacją, co to jest. Podczas rysowania nowego schematu wygeneruj plik PDF i wyślij go do wszystkich osób, które mogą być zainteresowane. Zalety poczty elektronicznej to:

  1. Ludzie zwykle sprawdzają pocztę e-mail, podczas gdy nikt nie przegląda folderu o nazwie „doc”.

  2. Wiadomość e-mail istnieje w kontekście, w otoczeniu innych wiadomości e-mail omawiających funkcję i powiązane funkcje oraz wszystko inne, co działo się w tym czasie.

  3. Wiadomość e-mail jest krótka, skoncentrowana i ma temat.

  4. E-mail pozwala osobom, które chcą zadawać pytania od razu,

  5. E-mail jest wysoce przeszukiwalny, ponieważ ludzie używają go do wszystkiego, a klienci poczty znacznie się rozwinęli przez lata.

  6. Jeśli jest w wiadomości e-mail, co najmniej jedna inna osoba wie, gdzie go znaleźć.

Teoretycznie powinno się wydawać, że komentarze w kodzie powinny być również „aspektami twojego dnia, które i tak zawsze robisz”, ale szczerze mówiąc, nigdy nie czytam komentarzy w kodzie. Nie jestem pewien, dlaczego, ale po prostu nie są bardzo pomocne, może dlatego, że brakuje kontekstu, który rozwiązuje e-mail.

piekarnik
źródło
z wyjątkiem # 4 („osoby, którym zależy na zadaniu pytań od razu”), żadna z wymienionych przez ciebie korzyści e-mail nie działała dla mnie niezawodnie. 1: Ludzie zwykle ignorują wiadomości e-mail, gdy jest ich dużo. 2: E-mail często ma tendencję do gubienia kontekstu, zakopywania go w problemach ubocznych i nadmiernego cytowania. 3: E-maile są zbyt często długie / duże i mają tendencję do utraty koncentracji w miarę wchodzenia w dyskusję. więcej problemów ubocznych i tematów jest często nieistotnych / przestarzałych („Re: WTF wydarzyło się dziś na serwerze?”) ...
skomentuj
... 5: Wyszukiwanie wiadomości e-mail jest wysoce zagrożone przez możliwość usuwania wiadomości e-mail, funkcję, którą ma każdy porządny mailer i każdy aktywny użytkownik poczty, używa dużo 6: patrz 5, jeśli poczta zostanie usunięta, nikt nie będzie w stanie znajdź go (jedyne, na czym mogę polegać, to wyszukiwanie moich wysłanych wiadomości e-mail, a to tylko dlatego, że bardzo staram się ich nie usuwać). Poza pochwałami przez e-mail (co wydaje mi się dość nieuzasadnione), robisz kilka dobrych rzeczy
zgryź
@gnat Przypuszczam, że może to różnić się w zależności od firmy w zakresie usuwania. W mojej firmie przechowujemy wszystkie wiadomości e-mail, a także archiwa wszystkich wiadomości e-mail od byłych pracowników i za każdym razem, gdy nowa osoba rozpoczyna zadanie, przekazujemy jej wszystkie powiązane wiadomości e-mail. Przypuszczam różnicę w stylu.
Owen,
tak, to zależy bardzo od stylu / kultury. Podczas gdy „zwalczanie usuwania” jest z pewnością wykonalne (a nawet technicznie proste do osiągnięcia poprzez eksportowanie wątków poczty na jakiś serwer), rzeczy takie jak utrzymywanie ich skupienia, wiersze tematyczne istotne, cytowanie ograniczone do rozsądnych limitów jest sprawą bardzo kulturową, wymagającą sporo wysiłku i determinacji (oraz wsparcie w zarządzaniu), aby utrzymać ... w porównaniu do tego wysiłku, a przede wszystkim na potrzebę MGMT buy-in, utrzymując rzeczy jak komentarzach wiki / code / foldery doc może okazać się po prostu łatwiej
gnat