Style komentowania / dokumentacji w kodzie

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?

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 ¹ 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.}

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.

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

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.

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

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
{
 ...
}

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.