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

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?

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.

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.

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.

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

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.

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.