Czy komentarze są uważane za formę dokumentacji?

11

Kiedy piszę dla siebie małe skrypty, układam swój kod wysoko w stos z komentarzami (czasami komentuję więcej niż koduję). Wiele osób, z którymi rozmawiam, mówi, że powinienem dokumentować te skrypty, nawet jeśli są one osobiste, więc jeśli kiedykolwiek je sprzedam, będę gotowy. Ale czy komentarze nie są formą dokumentacji?

Czy to nie:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

być uważana za dokumentację, szczególnie jeśli programista używa mojego kodu? A może dokumentację uważa się za poza samym kodem?

Dynamiczny
źródło
11
Jeśli używasz systemu generowania dokumentów, takiego jak JavaDocs lub Doxygen, komentarze są dosłownie dokumentacją.
Gort the Robot
5
YANGNI ( xprogramming.com/Practices/PracNotNeed.html ). Udokumentuj swój kod według własnego uznania. Pozwól klientowi (jeśli taki istnieje) zapłacić Ci za napisanie dokumentacji zgodnie z ich wymogami. Nie martw się o to, co mówi wiele osób (chyba że ci płacą).
emory
1
Z twoich 2 komentarzy drugi jest bezużyteczny, dlaczego nie zastąpić $ foo paskiem. Jeśli nie jest to prawdą, to komentarz jest błędny. Pierwszy komentarz jest błędny. To zadanie.
ctrl-alt-delor
2
Kiedykolwiek chcesz dodać komentarz, zmień kod tak, aby był tak wyraźny, że nie wymaga komentarza. Wszystko jest dokumentacją, kod jest dokumentacją, Komentarze zwykle nie zawierają [dodatkowych] informacji lub są błędne. Udokumentuj zamiar, co (umowy kodowe mogą w tym pomóc) i dlaczego. Trzymaj dokumentację blisko kodu, używaj komentarzy. Dokumentacja nad dokumentami: Komentarze nad dokumentami, Wyczyść kod nad komentarzami.
ctrl-alt-delor
2
Czy YANGNI „nie będzie ci to potrzebne”
Chris S

Odpowiedzi:

27

Komentarze są zdecydowanie dokumentacją. W przypadku większości projektów komentarze są (niestety) podstawową (jeśli nie tylko) formą dokumentacji projektowej. Z tego powodu bardzo ważne jest, aby zrobić to dobrze. Musisz upewnić się, że dokumentacja pozostaje dokładna pomimo zmian w kodzie. Jest to częsty problem z komentarzami. Programiści często „stroją” je, gdy pracują w znanym kodzie, więc zapominają aktualizować komentarze w celu odzwierciedlenia kodu. Może to tworzyć nieaktualne i wprowadzające w błąd komentarze.

Wiele osób sugeruje, aby kod sam się dokumentował. Oznacza to, że zamiast komentarzy restrukturyzujesz swój kod, aby wyeliminować jego potrzebę. Może to pozbyć się większości komentarzy „co” i „jak”, ale tak naprawdę nie pomaga w komentarzach „dlaczego”. Chociaż może to skutecznie działać, aby pozbyć się większości komentarzy, wciąż wiele razy pisanie komentarza jest najprostszym i najbardziej wydajnym sposobem na udokumentowanie fragmentu kodu.

Oleksi
źródło
3
„W przypadku większości projektów komentarze są podstawową (jeśli nie tylko) formą dokumentacji projektowej.” - kusi, by głosować za tym, ale niestety należy to uznać za prawdziwe stwierdzenie. Mam jednak nadzieję, że nie zamierzacie twierdzić, że tak właśnie powinno być.
Edward Strange
2
Naprawdę się z tym nie zgadzam, ponieważ jedyną wiarygodną dokumentacją jest sam kod źródłowy. Zarówno komentarze, jak i „dokumentacja” muszą być przechowywane z kodem, co rzadko się zdarza. Więc jedynym wiarygodnym źródłem dokumentacji jest twój kod!
martiert
3
@martiert Kiedyś czułem to samo, ale stwierdziłem, że to nie działa tak dobrze w praktyce. Wszystkie te komentarze „dlaczego” są znacznie wyraźniejsze jako komentarze niż próba wydobycia wiedzy „dlaczego” z kodu. Z pewnością kod do samodzielnej dokumentacji może (i powinien) zostać użyty do usunięcia większości komentarzy, ale czasami komentarz jest najprostszym, najczystszym i najbardziej efektywnym czasowo sposobem na udokumentowanie czegoś.
Oleksi
3
@martiert Problem z kodem samodokumentującym polega na tym, że nie pozwala on na odwołania do dokumentacji w innym miejscu. Niektóre z najlepszych komentarzy w kodzie, jakie kiedykolwiek widziałem, to odniesienia do prac naukowych wyjaśniających szczegóły zastosowanego algorytmu lub wybór magicznych stałych. Żadna ilość samo-dokumentacji nie pomoże uniknąć tego, że niektóre krytyczne dokumenty są po prostu nieoczywiste. „Dlaczego” często należy do tej kategorii, a czasem także „jak”.
Donal Fellows
3
Zauważ również, że komentarze w wielu językach są używane do generowania faktycznej dokumentacji ... więc często są one takie same. Zobacz MSDN jako przykład.
Steven Evers
12

Są formą dokumentacji, ale pamiętaj, że dokumentacja jest w oczach patrzącego ...

  • Dla niektórych wystarczy samokodujący się kod . Ale zakłada to poziom szczegółów technicznych jako klienta. Powinniśmy uważać, że to wystarczy, ponieważ nasze ego może powiedzieć nam „To oczywiste, co robi ten kod”, ale czas może okazać się inny. Zakłada również, że znasz z góry umiejętności czytelnika.

  • Dla tych, którzy patrzą na kod źródłowy, ale z mniejszą wiedzą techniczną, komentarze mogą być w porządku. Ale to zakłada, że ​​ktoś patrzy na kod źródłowy.

  • Jeśli jesteś techniczny, ale nie masz czasu na przeczytanie całego kodu źródłowego, może być wymagana instrukcja techniczna .

  • Jeśli użytkownik nie ma umiejętności technicznych, ale musi tylko wiedzieć, co się dzieje, potrzebna jest dokumentacja użytkownika .

Tak więc prawdziwe pytanie brzmi: kto jest twoim klientem? Jeśli tak, wystarczy samokontraktujący się kod lub komentarze. Jeśli jest to dla kogoś innego, możesz poszerzyć sposób dokumentowania.

MathAttack
źródło
17
Kod samodokumentujący to kłamstwo.
yannis
1
@YannisRizos Bardziej jak nieosiągalny cel niż zwykłe kłamstwo.
Ptharien's Flame
2
@YannisRizos: możesz mieć rację, ale kod, który wymaga wielu komentarzy, jest prawie zawsze bardzo złym kodem i prawie zawsze może być napisany w taki sposób, że potrzebuje mniej komentarzy.
Doc Brown
9
@DocBrown Zależy. Widziałem ludzi dokumentujących pętle i widziałem ludzi twierdzących, że logika biznesowa 100 loc była dokumentowaniem siebie. Faktem jest, że nadmierne komentarze nie mogą zaszkodzić (chyba że są przestarzałe / niepoprawne), a jeśli będę musiał wybierać między nadmiernym komentowaniem a kodem samodokumentującym, zawsze wybiorę pierwszy. Oczywiście wolałbym wyważone i rzeczowe komentarze, jak opisuje Oleksi .
yannis
1
@MathAttack Większość porządnych IDE może ukrywać / fałszować komentarze. Ale tak, czasami przeszkadzają.
yannis
3

Tak, komentarze są formą dokumentacji. Czy jest to przydatna dokumentacja dla kogoś, kto musi utrzymywać lub aktualizować kod, jest pytaniem otwartym.

Wiem, że miałeś na myśli ten przykład, ale takie rzeczy

print $foo; # this prints "bar"

nie jest użyteczny; po prostu dodaje bałaganu wizualnego. Nie dokumentuj rzeczy oczywistych.

Blokuj komentarze na początku metody lub definicji funkcji, które opisują funkcję lub cel metody (w kategoriach wysokiego poziomu ), przydatne są dane wejściowe, wyjściowe, zwracana wartość (jeśli istnieje), wyjątki (jeśli istnieją), warunki wstępne i dodatkowe, ale tylko w takim stopniu, w jakim mówią komuś, jak ma być używana funkcja lub metoda. Nie wyjaśniają, dlaczego funkcja istnieje.

Jeśli ktoś musi utrzymywać twój kod, musisz gdzieś udokumentować wymagania i projekt, a zwykle nie jest to zrobione w samym kodzie źródłowym.

John Bode
źródło
3

Uważam, że trzymanie się podejścia Boba Martina do tego, z Clean Code, zazwyczaj rozwiązuje problem, czy uważasz, że przesadzasz z komentowaniem, czy nie komentujesz i pomijasz dokumentację:

Jesteśmy autorami. Jedną rzeczą dotyczącą autorów jest to, że mają czytelników. Rzeczywiście, autorzy są odpowiedzialni za dobrą komunikację z czytelnikami. Następnym razem, gdy napiszesz wiersz kodu, pamiętaj, że jesteś autorem i piszesz dla czytelników, którzy ocenią twój wysiłek.

... stosunek czasu spędzonego na czytaniu do pisania wynosi znacznie ponad 10: 1. Cały czas czytamy stary kod w ramach pisania nowego kodu.

Innymi słowy, czy Twój kod nie wymaga wyjaśnień? Nie ma ustalonej reguły (chyba, że ​​pracujesz dla kogoś takiego jak Microsoft, którego dokumentacja jest publicznie dostępna), głównie z powodu pomocy przyszłym czytelnikom kodu, którym często jesteś.

Chris S.
źródło
2

Dokumentacja powinna udokumentować dlaczego nie How . Jak powinno być oczywiste w kodzie, który jest chyba to jest jakaś sztuczka optymalizacja arcane lub inna technika specyficzny język, który nie jest powszechnie występuje.

Dlaczego prawdopodobnie nie powinno być w kodzie, powinno być gdzieś indziej jak zaległości produktu, który jest przywiązany do popełnienia komentarzy z identyfikatorami historia, która może być znaleziony w dzienniku zmian lub nazwa oddziału.


źródło
1
Naprawdę trudne rzeczy powinny znajdować się w pracy naukowej (lub czasami patentowej).
Donal Fellows
2

Komentarze są formą dokumentacji. Niższa forma i taka, która sugeruje, że znalazłeś obszar swojego kodu, który można lepiej uwzględnić.

Wygląda na to, że komentujesz rzeczy kompulsywnie. Posiadanie innych opcji może być dobrą rzeczą. Mogę wymyślić trzy lepsze formy dokumentacji:

1) Popraw swój kod lepiej. Zamiast dodawać komentarz, wyodrębnij metodę lub funkcję, której nazwa jest tekstem komentarza, który miałeś napisać. Więc kod mówi, co miał powiedzieć Twój komentarz.

2) Testy. Jest to forma dokumentacji, której zwykle szukam. Testy jednostkowe i testy akceptacyjne są żywą dokumentacją i można je łatwo odczytać, jeśli stosuje się wiele znaczących metod wyrażania intencji, jak w pkt 1.

3) W przypadku skryptów opcja --help. To jest miejsce, w którym możesz zwariować na punkcie doc. Trzymaj się przykładów, przewiduj, czego użytkownik będzie potrzebował.

Podsumowując, jeśli masz skłonność do pozostawania w komentarzu, sprawdź, czy istnieje sposób na komunikację z czytelnikiem poprzez lepszą strukturę kodu. Czy jest test, który informuje, dlaczego ten kod istnieje? Jeśli nadal masz ochotę to skomentować, przyznaj się do porażki i zrób to.

Mike Hogan
źródło