Style komentowania / dokumentacji w kodzie

9

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?

Maks
źródło
twój przykład jest uproszczony. W praktyce należy podać znacznie więcej ograniczeń niż tylko typ parametru, jeśli jest to liczba całkowita, to musi to być liczba całkowita o wartościach X i Y. Jeśli zwracana wartość jest podwójna, możesz określić jej dokładność i jakie to mogą być wartości (może istnieć funkcja, która zwraca dokładnie 1,01, 2,31 i 5,01!). Bądź bardziej szczegółowy, a nie zobaczysz tyle powtórzeń ...
Stare konto

Odpowiedzi:

17

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.

Larry Coleman
źródło
1
+1, choć pamiętaj, że to, co jest dla ciebie oczywiste, może nie być oczywiste dla innego programisty.
Josh K,
@Josh: dobra uwaga, więc zredagowałem odpowiedź.
Larry Coleman,
@ Larry: Dobre komentarze powinny również obejmować: co wchodzi, co wychodzi, a zwłaszcza jaki typ wchodzi i wychodzi.
Joris Meys,
@Joris: To, co wchodzi i co wychodzi, jest objęte „oczekiwaniami dotyczącymi danych wejściowych” i „tym, jak zachowa się kod”. Jeśli chodzi o typ, który wchodzi i wychodzi, podtrzymuję to, co powiedziałem wcześniej: „Dobre komentarze nie powtarzają tego, co jest w kodzie”.
Larry Coleman,
2
@ Larry: Wolę czytać to w komentarzu niż przeglądać deklaracje i kod za każdym razem, gdy chcę ponownie użyć funkcji. Myślę, że to kwestia stylu. Jestem leniwym facetem.
Joris Meys,
6

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: MyFunctiongdy 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:

  • Podsumowanie (co robi i kiedy dotyczy podsumowanie tego, jak z niego korzystać)
  • Lista parametrów i oczekiwane
  • Jaka będzie wartość zwracana (wynik)
  • Wszelkie wyjątki, które mogą zostać zgłoszone wprost i dlaczego

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.

Berin Loritsch
źródło
Czy jest dopuszczalne, jeśli opis wyjściowy jest dołączony do podsumowania? Na przykład Returns the square root of Xopisuje również, jaka jest wartość zwracana.
Maks.
Tak; uczniowie powinni nauczyć się korzystać z tych funkcji dokumentacji.
Jeremy,
Jeśli to możliwe, chcę, aby dokumentacja API była bardziej logiczna. Na przykład Returns the color for this raylub Returns the requested Message, or null if it can't be found. Ale tak, podsumowanie jest podstawą dokumentów API.
Berin Loritsch,
3

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

Martijn Verburg
źródło
Czasami funkcje mogą zachowywać się w narożnikach, co różni się od tego, co sugerowałby algorytm. Na przykład zaokrąglenie a floatdo liczby całkowitej przez dodanie 0,5 i obniżenie wyniku spowoduje, że największy wynik float 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.
supercat
1

Jest to podobne do tego, jak większość frameworków -Doc analizuje dokumentację w kodzie (JavaDoc, PHPDoc itp.).

Z Java, automatycznie generowane przez IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

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.

Nicole
źródło
1

Komentarze mają dwa cele:

  1. Służą one do szybkiego przypomnienia Ci, co robi Twój kod, gdy wrócisz do niego miesiące / lata później. W ten sposób nie musisz ponownie czytać i analizować kodu, aby odświeżyć pamięć.
  2. Przekazują innym osobom, które mogą czytać lub pracować z Twoim kodem, co robi Twój kod.

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:

a += 1; //adds 1 to the value in a

Naprawdę? Dzięki! lol

Kenneth
źródło
0

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.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

I jak powiedział @Larry Coleman, wbudowane komentarze powinny powiedzieć, dlaczego napisałeś jakiś fragment kodu.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}
Radu Maris
źródło
0

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.

dietbuddha
źródło