Czy uważasz, że kod sam się dokumentuje? [Zamknięte]

To pytanie postawiono mi wiele lat temu jako absolwent podczas rozmowy o pracę i od czasu do czasu dokucza mi mózg i tak naprawdę nigdy nie znalazłem dobrej odpowiedzi, która by mnie zadowoliła.

Ankieter, o którym mowa, szukał czarno-białej odpowiedzi, nie było pośredniego uzasadnienia. Nigdy nie miałem okazji zapytać o uzasadnienie pytania, ale jestem ciekawy, dlaczego to pytanie zostało postawione twórcy i czego nauczyłbyś się z odpowiedzi tak lub nie?

Z mojego punktu widzenia potrafię czytać Java, Python, Delphi itp., Ale jeśli mój menedżer podejdzie do mnie i zapyta, jak daleko jestem w projekcie, i powiem „Kod jest kompletny w 80%” (i wcześniej zaczynasz mnie zastrzelić, słyszałem to wypowiedziane w kilku biurach przez programistów), jak dokładnie to samo dokumentowanie? Przepraszam, jeśli to pytanie wydaje się dziwne, ale wolałbym zadać i uzyskać opinie na jego temat, aby lepiej zrozumieć, dlaczego ktoś miałby zostać przesłuchany w wywiadzie.

Częściowo.

Kod, który używa Big English Words, może być częściowo samodokumentujący, ponieważ nazwy wszystkich funkcji i zmiennych informują o tym, co robi. Ale prawdopodobnie nie powie ci dlaczego.

Porównać:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Ale nadal nie wiesz, dlaczego uruchamia się samochód. Stąd tylko częściowo. To trochę okropne, że twój ankieter oczekiwał czarno-białej odpowiedzi, chyba że jego pogląd na czarno-biały zawierał może bardzo silną odpowiedź.

Nie. Kod sam w sobie nie dokumentuje się sam.

Powodem jest to, że kod określa JAK i nie obchodzi go DLACZEGO ludzie powinni wiedzieć, aby zachować kod.

Dlatego potrzebujesz dodatkowych komentarzy wyjaśniających wszystkie DLACZEGO . Możesz je ograniczyć, pozwalając, aby nazwy zmiennych zawierały część decyzji, ale nie możesz ich uniknąć.

Właściwy kod mówi „ jak ”. Odpowiednie komentarze mówią „ dlaczego ” .

Dlatego kod może samokontraktować sposób, w jaki się to osiąga, ale nie można zakładać, że dokumentuje powód.

Jeśli nalegają na czarno-białą odpowiedź bez pośredniego podłoża, odpowiedź brzmi „nie”.

Bardziej kompletną odpowiedzią jest to, że kod powinien samokontraktować się w maksymalnym rozsądnym zakresie, ale nie ma rozsądnego sposobu włączenia niektórych rodzajów dokumentacji do kodu. Na przykład kod może zrobić grzywnę tylko dokumentując, jakie informacje są gromadzone w formularzu A, co w formularzu B, a co w formularzu C. Zasadniczo nie będzie (i prawdopodobnie nie powinno) próbować udokumentować testów wykazujących ten podział dane w ten sposób zmniejszyły liczbę błędów x% w porównaniu do (na przykład) przy użyciu tylko dwóch formularzy zamiast trzech.

Wszystko, oprócz najbardziej trywialnego fragmentu kodu, może korzystać z przynajmniej części dokumentacji zewnętrznej.

Moja odpowiedź. W największym możliwym stopniu powinieneś dążyć do tego, aby Twój kod był tak samo dokumentujący jak to możliwe. Jest wiele powodów. Na początku napisano, że średnio jedna linia na 10 ma błąd. Błędy w kodzie można znaleźć i naprawić. Błędy w dokumentacji zwykle pozostają. A w konserwacji często kod i dokumentacja rozpadają się.

To powiedziawszy, istnieją ograniczenia co do tego, co można zrobić, wyjaśniając kod. W takich przypadkach musisz udokumentować.

Co ze sprawą, w której masz wybór dotyczący dokumentacji? Uważam, że utrzymanie zależy w dużej mierze od organizacji. Jeśli masz doskonałych programistów i rygorystyczny proces sprawdzania kodu (jak na przykład Google), to Twój proces i ludzie mogą być tacy, że nie musisz się martwić o to, że komentarze nie zostaną utrzymane. W takim przypadku dużo bardziej sensowny styl ma dużo komentarzy. (Google ma w rzeczywistości styl z dużą ilością komentarzy.) Jednak jeśli masz bardziej typową organizację, to bardzo nie ufam żadnym komentarzom, które widzę, i mam nadzieję, że masz ludzi, którzy wierzą w próbach samodokumentowania kodu. W tej sytuacji uważam komentarze za zbyteczne.

Interesującą rozmowę na temat zalet i wad komentowania można znaleźć na stronie http://www.perlmonks.org/index.pl?node_id=65153, gdzie znajduje się stara rozmowa, w której uczestniczyłem. (Uwaga: w tym samym czasie, gdy odbyliśmy tę rozmowę, był prywatny zestaw rozmów, które były bardziej przyjazne. Zawsze żałowałem, że tylko bardziej negatywna połowa rozmowy jest publiczna.) Moje opinie nie pasują już dokładnie do tego, co wtedy myślałem , ale nadal uważam, że ta rozmowa jest warta przemyślenia.

Uważam, że to pytanie pojawia się często i często wywołuje w nim religijny zapał. Oto moje zdanie na ten temat ...

W idealnym świecie można by sformułować następujące oświadczenie:

Kod powinien być napisany w taki sposób, aby logika mogła być przestrzegana bez potrzeby komentowania.

OK, to dość sprawiedliwe, ale problem polega na tym, że nie żyjemy w idealnym świecie. Istnieją pewne problemy z osiągnięciem tego idealnego stwierdzenia.

1. Programiści często nie są ekspertami w branży, przeciwko której programują. Łatwo jest zrozumieć funkcję taką jak startEngine(Car car)(większość) każdy może zrozumieć, o co tu pytamy. Ale przenieś się do prawdziwego świata, a sprawy staną się nieco bardziej niewyraźne. Na przykład funkcja getSess(String tid, String aid)ta byłaby doskonale zrozumiała dla inżyniera transportu, który rozumiał systemy DWDM, ale może stanowić wyzwanie dla nowego programisty, który właśnie uruchomił projekt. Dobrze umieszczone komentarze mogą ułatwić przejście do zrozumienia kodu w odpowiednim czasie.

2. Programiści proszeni o utrzymanie kodu często nie są tak wykwalifikowani jak oryginalni architekci kodu. Pierwotny programista mógł być wystarczająco wykwalifikowany, aby napisać szybki, zwięzły i wydajny algorytm do wykonania określonego zadania. Ale programista, którego zadaniem jest utrzymanie tego kodu, może mieć problem z próbą zrozumienia, co się dzieje. Dobrze umieszczone komentarze mogą ułatwić przejście do zrozumienia kodu w odpowiednim czasie.

3. Ile razy napisałeś trochę kodu, z którym później starałeś się zrozumieć, dlaczego to zrobiłeś, a nawet co próbujesz osiągnąć? Wszyscy to robimy od czasu do czasu. Rozwiązanie problemu i stworzenie łatwego do rozwiązania rozwiązania problemu to często dwa różne sposoby myślenia. O ile nie jesteś osobą, która potrafi perfekcyjnie pisać kod z bramki, często popełniasz błędy w swoim kodzie. Być może na jakiś czas nie będziesz mógł wrócić do tego fragmentu kodu. Dobrze umieszczone komentarze mogą ułatwić przejście do zrozumienia kodu w odpowiednim czasie.

4. Unikalne sytuacje wymagają wyjaśnienia. Na przykład programista może zastanawiać się, dlaczego wstawiono pauzę 100 ms w kawałek kodu komunikującego się z urządzeniem DWDM. Powiadomienie następnego programisty, że potrzebna jest pauza, ponieważ urządzenie jest wolne w pobieraniu i może pominąć polecenie, byłoby cenną informacją. Dobrze umieszczone komentarze mogą ułatwić przejście do zrozumienia kodu w odpowiednim czasie.

Ładnie napisany „samodokumentujący” kod to przyjemność. Ładnie napisany, „samodokumentujący” kod, z dobrze umieszczonymi, pouczającymi komentarzami, jest darem niebios i bardzo rzadkim znaleziskiem.

Wystarczy podać argumenty po każdej stronie pytania początkowego:

Tak, kod sam się dokumentuje. Zmienne, metody i nazwy klas można uczynić tak, aby były łatwe do odczytania i zrozumienia, dzięki czemu jest to forma samo-dokumentowania. W stylu kodu może znajdować się coś, co daje dokumentację XML na końcu, co jest uważane za standardową procedurę. Innymi słowy, zadaniem dewelopera jest dostarczenie dokumentacji, która może zostać zmiksowana z kodem.

Nie, kod nie dokumentuje się sam. Podjęte decyzje biznesowe, dokonane wybory projektowe i inne czynniki nie pojawią się w liniach kodu i powinny zostać zapisane poza bazą kodu. Dlatego niezbędna jest zewnętrzna dokumentacja i są to jej przykłady.

Pytanie: czy udzielisz częściowej odpowiedzi, uznając ograniczenia odpowiedzi, czy ślepo oprzesz się po którejkolwiek stronie, według ciebie, lepszej praktyce? Ile masz przekonania w swojej odpowiedzi, jeśli jest to tak lub nie? Może to być postrzegane jako stresujące pytanie, które ma na celu wzbudzenie u kogoś, kto może odpowiedzieć: „Co do ...? To najgłupsze pytanie, jakie możesz mi kiedykolwiek zadać. Nie odpowiadam na to z tego powodu, że obraża moja inteligencja nie do uwierzenia! ” jako raczej arogancką i pompatyczną odpowiedź, którą mogłem sobie wyobrazić, że niektórzy ludzie udzielają odpowiedzi tym tonem.

Oczywiście był kompetentnym programistą w stylu Knutha. Dla ucznia LP kod musi być samo-dokumentujący, aby był ważny. Zatem jedyną możliwą odpowiedzią jest „tak”.

Problem polega na tym, że nie ma wielu piśmiennych języków programowania i nie znam żadnego z nich w powszechnym użyciu komercyjnym. Musiałaby to być gdzieś niszowa pozycja.

Sądzę, że ankieter mógł szukać: „Jak piszesz samokodujący się kod?” z dorozumianym „Jakie jest twoje podejście do dokumentacji?”

Byłem kiedyś na naprawdę inspirującym wykładzie faceta o nazwisku Robert C. Martin, gdzie mówił o rozdziale „metod pisania” w swojej książce Clean Code.

Najwyraźniej prezentował nieco stanowisko purysty, ale skorzystałem z jego rady, że kiedy dzielisz swój kod na małe metody wielokrotnego użytku i używasz prostych sztuczek, takich jak:

• Utrzymywanie wszystkich instrukcji w metodzie na tym samym poziomie abstrakcji
• Wyciąganie zawartości warunków przepływu sterowania lub bloków pętli do wywołań metod
• Gdy przekonasz się, że przekazujesz te same parametry do kilku metod w klasie, wyodrębniasz nową klasę
• I proste sztuczki, takie jak zastąpienie tajemniczych wyrażeń logicznych wywołaniami metod
• itp...

W efekcie powstaje czytelny, nieco samodokumentujący się kod (o ile wkładasz wysiłek w zwięzłe, ale opisowe nazwy), który jest łatwiejszy do zrozumienia i utrzymania.

Uważam, że te rzeczy są naprawdę pomocne, ale do prawidłowego działania wymagana jest znajomość wzorców projektowych i zdecydowanie musisz uzupełnić to podejście dokumentacją klasową i metodyczną na wysokim poziomie.

Zwykle kod samodokumentujący odnosi się do praktyki korzystania z konwencji nazewnictwa dla zmiennych, funkcji itp., Tak aby cel kodu był oczywisty. Tak więc żaden kod sam w sobie nie jest samodokumentowaniem. Nie rozumiem, o czym mówisz w trzecim akapicie. Wydaje się, że nie ma to nic wspólnego z kodowaniem samokontrującym.

Jack Reeves przekonywał, że kod jest projektem . Jeśli chodzi o wielu, faktyczny kod jest jedynym „dokumentem”, który mówi ci, co robi system. Wszystko inne rozpada się, ponieważ system na żywo ma tendencję do oddalania się coraz bardziej od zaprojektowanego systemu. Nawet jeśli miałbyś wygenerować dokument z kodu (jak wiele współczesnych narzędzi UML może to zrobić), nadal jest to tylko dokładna dokumentacja systemu w tym momencie .

Więc tak, kod jest samodokumentujący. Jak dobrze jest to udokumentowane, to kolejne pytanie.

W miarę zdobywania doświadczenia, nauczyłem się, że prawdziwą odpowiedzią jest to, że kod plus środowisko czytelnika określa poziom samodokumentacji.

Aby zminimalizować różnice między środowiskiem czytelnika a środowiskiem pisarza, dodajemy komentarze. Im więcej potrzebnych komentarzy, zwykle tym mniej doświadczony pisarz. Istnieje dość wspaniały esej opisujący ten aspekt tworzenia oprogramowania, ale nie pamiętam, kto go napisał ani gdzie go znalazłem.

Wiem, że większość ludzi oczekuje na to pytanie „nie”, ale powiem tak. Gdybym został o to poproszony podczas rozmowy kwalifikacyjnej w sprawie pracy, nadal powiedziałbym, że tak.

Pracowałem nad wieloma różnymi projektami z otwartym i zamkniętym źródłem. Różniły się one w dokumentacji od prostych komentarzy pozostawionych jako uwagi programisty do pełnych dokumentacji API. Chociaż dokumentacja API może być świetna, zawsze w końcu dotarłem do sytuacji, w której dokumentacja w języku pisanym była niewystarczająca, aby określić rzeczywiste zachowanie kodu. W końcu popatrzyłem na kod źródłowy, dokonałem inżynierii wstecznej aplikacji lub nękałem programistów dostępem do źródła, aby spojrzeć na kod źródłowy i sprecyzować go dalej.

Dla mnie kod jest najlepszą dokumentacją. Bez względu na to, ile napiszesz słowami, co program zrobi, dokładne zachowanie jest określone przez kod.

Zgadzam się, że pisząc kod, powinieneś postarać się, aby kod był jak najbardziej samoopisujący. Jednak, jak wspomnieli inni, w złożonym programie prawie niemożliwe jest całkowite opisanie wszystkiego, co robi kod. Nie jestem przeciwny komentarzom, w rzeczywistości uważam, że dzięki dobrym komentarzom łatwiej jest czytać kod, nawet jeśli kod mógłby się wyjaśnić bez komentarzy czytających po angielsku lub jakiś język mówiony jest prawie zawsze łatwiejszy.

Przekonałem się, że najbardziej użyteczną dokumentacją są prawie nigdy komentarze. Większość projektów, nad którymi ostatnio pracuję, zawiera wiki zawierające wszystkie różne części, jak się łączą. Próbuję wyjaśnić, co miałem na myśli, kiedy pisałem kod, aby inni ludzie nie złamali mojego kodu, ponieważ nie rozumieli, dlaczego. Może również pomóc komuś innemu zmienić kod z większą pewnością. Często waham się nad kodem refaktoryzującym, ponieważ nigdy nie wiem, co może się zepsuć i nie ma wyjaśnienia. Nawet jeśli jesteś jedyną osobą pracującą nad projektem, który gwarantuję za rok lub dwa, zapomnisz, dlaczego coś zrobiłeś, nawet jeśli jest to najpiękniejszy fragment kodu, wciąż możesz zapomnieć, dlaczego on tam jest.

Jasne, jeśli masz nieograniczony czas. Ponad 25 lat spędziłem na dokumentowaniu kodu dla innych programistów. Moje stanowisko zawsze było takie, że staram się coś wyjaśnić, aby inny programista mógł przejrzeć to w 5 minut, kiedy mogli po prostu zbadać kod i znaleźć go w pół godziny. Jeśli oszczędzę wszystkim, którzy patrzą na tę metodę, 25 minut, to wykonam swoją pracę.

Myślę, że do dokumentowania kodu należy zawsze używać diagramu klas. Nie sądzę, że jeśli spojrzysz bezpośrednio na kod, zobaczysz pełną architekturę. Zgadzam się, że jeśli sam napisałeś kod lub pracujesz nad nim przez długi czas, możesz zrozumieć, ale za każdym razem, gdy pojawia się nowe żądanie, za każdym razem musisz spojrzeć na kod i szukać, gdzie dodać ten nowy kod.

To, co robimy w naszej firmie, to mieć schematy klasowe naszego projektu. Tak naprawdę nie spędzamy czasu na modelowaniu, ale używamy diagramu klas do wizualizacji kodu po inżynierii odwrotnej. Jeśli kod się zmieni, to istnieje mechanizm scalania, a diagramy moich klas są zawsze aktualizowane.

To, co jest fantastyczne, to możliwość dodawania komentarzy, ograniczeń do diagramu oprócz java doc. Odwracamy projekt, a następnie tworzymy model i ostatecznie wyodrębniamy widoki z modelu wyświetlanego jako diagramy klas UML. Na tym etapie nie koduję, ale otrzymuję niebieski druk z architektury kodu i pracuję nad tym, aby utworzyć lub rozszerzyć moją obecną architekturę. Jeśli mi się podoba, to wciskam przycisk i mój istniejący kod łączy się z moimi diagramami. Mam na myśli scalanie, a na pewno nie pełne generowanie kodu. Zapisywana jest tylko różnica między istniejącym kodem a moimi diagramami, a nie pełny kod za każdym razem.

Studiuję od wielu lat, mam tytuł magistra i nadal koduję, ale nie chcę być tylko pisarzem Java i chciałbym trochę więcej wykorzystać mój mózg. Widoki UML dają mi to, czego potrzebuję, aby myśleć o mojej architekturze, komunikować się z innymi członkami zespołu i tworzyć lepszą architekturę bez korzystania z programowania Model Driven, ale tylko różnicę między istniejącym ręcznie pisanym kodem i graficznie tworzyć diagramy klas. Tworzę moją architekturę na poziomie kodu, a następnie odwracam ją i patrzę na model. Tworzę widoki i próbuję ulepszyć moją architekturę bezpośrednio w kodzie, a następnie ponownie odwrócić i zobaczyć, co się dzieje itp. Jest to ciągła iteracja bez generowania kodu sterowanego przez model, ale synchronizacja na żywo lub scalanie między kodem a UML. Podoba mi się to, że kod napędza UML i na pewno nie jest odwrotnie.