To może być głupie pytanie, ale przez jakiś czas było w mojej głowie i nigdzie indziej nie mogę znaleźć porządnej odpowiedzi.
Mam nauczyciela, który mówi, że powinniśmy wyraźnie wymienić każdy parametr z opisem, nawet jeśli jest tylko jeden. Prowadzi to do wielu powtórzeń:
double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.
Jak szczegółowo piszesz dokumentację w kodzie?
Odpowiedzi:
Na początek zgadzam się, że wiersz „Function:” w twoim przykładzie jest całkowicie zbędny. Z mojego doświadczenia wynika, że ludzie uczyli w szkole dodawania tego typu komentarza, kontynuując dodawanie tego typu komentarza w kodzie produkcyjnym.
Dobre komentarze nie powtarzają tego, co jest w kodzie. Odpowiadają na pytanie „Dlaczego?” zamiast „Co?” albo jak?" Obejmują oczekiwania dotyczące danych wejściowych, a także zachowania kodu w określonych warunkach. Obejmują, dlaczego wybrano algorytm X zamiast algorytmu Y. Krótko mówiąc, dokładnie rzeczy, które nie byłyby oczywiste dla kogoś innego 1 po przeczytaniu kodu.
1: Ktoś inny, kto zna język, w którym napisany jest kod. Nie pisz komentarzy, aby uczyć, komentarzy w celu uzupełnienia informacji.
źródło
Kilka języków ma funkcje generowania dokumentów API, takie jak Ruby, Java, C # i C ++ (za pomocą narzędzia wiersza poleceń). Kiedy myślisz o tym w ten sposób, znacznie ważniejsze jest pisanie dokumentów API. W końcu odpowiada na pytanie „jak to zrobić ...?” Więc nie zrobię nic powtarzającego się, na przykład
Function: MyFunction
gdy nazwa funkcji będzie zrozumiała dla wszystkich. Narzędzia do generowania dokumentów API są wystarczająco inteligentne, aby to dla mnie zrobić. Przydatne są jednak następujące szczegóły, zwłaszcza dotyczące publicznych metod / funkcji:Mogą one stać się przydatnymi narzędziami odniesienia podczas próby debugowania kodu. Wiele IDE będzie również używać dokumentów API w podpowiedziach, gdy najedziesz kursorem na nazwę funkcji.
Jeśli jest to język bez tych funkcji, komentarze pomagają, ale nie tak bardzo.
źródło
Returns the square root of X
opisuje również, jaka jest wartość zwracana.Returns the color for this ray
lubReturns the requested Message, or null if it can't be found
. Ale tak, podsumowanie jest podstawą dokumentów API.Jeśli jest to publiczna metoda API, to tak, powinieneś dostarczyć szczegółową dokumentację, szczególnie dotyczącą parametrów i oczekiwanego zachowania. Wiele osób uważa, że można to złagodzić w przypadku prywatnych metod / funkcji, YMMV.
Ogólnie wolę pisać czysty kod (małe metody / funkcje, które dobrze wykonują jedną i jedną rzecz) z rozsądnymi nazwami zmiennych. To sprawia, że znaczna część twojego kodu sam się dokumentuje. Jednak z pewnością zawsze dokumentuję wszelkie przypadki brzegowe, zastosowania współbieżności i złożone algorytmy.
Krótko mówiąc, pomyśl o sobie jako o trochę gorszym w noszeniu o 3 nad ranem za 3 miesiące od teraz. Będziesz wdzięczny sobie za niesamowite publiczne dokumenty, zamiast zastanawiać się, co oznacza parametr (flaga logiczna) ...
źródło
float
do liczby całkowitej przez dodanie 0,5 i obniżenie wyniku spowoduje, że największy wynikfloat
poniżej 0,5 zostanie błędnie zaokrąglony w górę. W takich przypadkach czasami może być ważne rozróżnienie, czy funkcję należy zdefiniować jako zaokrąglenie do najbliższej liczby całkowitej (lub następnej wyższej liczby całkowitej, gdy dwie możliwe wartości są jednakowo odległe), lub jako dodanie 0,5 (ewentualnie z pośrednim krokiem zaokrąglania) i zabranie głosu w wyniku.Jest to podobne do tego, jak większość frameworków -Doc analizuje dokumentację w kodzie (JavaDoc, PHPDoc itp.).
Z Java, automatycznie generowane przez IDE:
Jest to ten sam format, który jest używany do generowania Dokumentacji dla wbudowanych funkcji językowych - Przykład: http://download.oracle.com/javase/6/docs/api/java/lang/String.html
Ten format jest bardzo pomocny, ponieważ wyraźnie pokazuje każdemu użytkownikowi zewnętrznemu, jak połączyć się z twoim kodem. Jeśli twoje funkcje są prywatnymi metodami, które są używane tylko wewnętrznie, może to być trochę bezcelowe - ale zgaduję, że twój nauczyciel stara się wprowadzić cię w dobrą praktykę, dopóki wszyscy nie doświadczą tego rozróżnienia.
Jedyne, co często uważam za nieco zbędne, to opis zwrotu - zwykle jest prawie identyczny z opisem mojej metody.
źródło
Komentarze mają dwa cele:
Oczywiście istnieje wiele WIELE różnych sposobów, ale im bardziej dokładny i konsekwentny, tym lepiej. Efektywne komentowanie wymaga czasu, podobnie jak efektywne programowanie. Pamiętaj, że ciężko jest dostrzec sens komentarzy w szkole, ponieważ nic, nad czym pracujesz, nie jest na tyle duże, aby naprawdę na to zasługiwać, ale starają się to przedstawić. I zwykle sposób, w jaki Cię tego uczy, to styl profesora, a nie jakikolwiek standard. Rozwiń, co Ci odpowiada. I pamiętajcie ... istnieje coś takiego jak głupi komentarz! :) Przykład:
Naprawdę? Dzięki! lol
źródło
Lubię dokumentację ze strony PHP, więc używam czegoś podobnego do moich wbudowanych komentarzy i używając składni PHPDoc. Zobacz przykład poniżej.
I jak powiedział @Larry Coleman, wbudowane komentarze powinny powiedzieć, dlaczego napisałeś jakiś fragment kodu.
źródło
Jeśli służy to generowaniu dokumentów, pełne komentarze (choć irytujące) są prawdopodobnie dobrą rzeczą. Chociaż celem zespołu jest pozostawanie na bieżąco z komentarzami i ich aktualizowanie.
Jeśli to tylko styl komentowania, miałbym z tym problem. Nadmierne komentarze mogą zranić kod tak samo jak pomoc. Nie mogę policzyć, ile razy natknąłem się na komentarze w kodzie, które były nieaktualne i dlatego wprowadzały w błąd. Zazwyczaj ignoruję teraz komentarze i skupiam się na czytaniu kodu i testach kodu, aby zrozumieć, co robi i jakie jest jego przeznaczenie.
Wolałbym mieć jasny, zwięzły, nieskomentowany kod. Daj mi kilka testów z opisowymi stwierdzeniami lub metodami, a ja jestem szczęśliwy i poinformowany.
źródło