Kilka słów na początek.
Cykl artykułów postanowiłem zacząć od opisania zastosowania i znaczenia komentarzy w kodzie źródłowym. Moim subiektywnym zdaniem używanie komentarzy stanowi bardzo ważną część przejrzystego i czytelnego programowania. Wielu programistów uważa, że komentarze są zbędę, a kod da się napisać w czytelny sposób bez stosowania komentarzy. W tym miejscu zgodzę się, że kod da się napisać w czytelny sposób stosując wiele innych zasad, lecz nie oznacza to, że komentarze będą przeszkadzać. Stosowanie komentarzy nie zwalnia przecież programisty z pisania kodu w sposób zrozumiały. Stosując starannie przemyślane komentarze da się znacznie skrócić czas na poprawne zrozumienie napisanego fragmentu kodu.
Nie będę się dalej rozpisywał nad ewentualnymi wadami, a w zasadzie pułapkami stosowania komentarzy bo w tym miejscu szkoda na to czasu. Jeśli będziecie mieli życzenie, aby taki wpis znalazł się na blogu, dajcie mi znać w komentarzu 😉 lub wyślijcie wiadomość e-mail.
Zakres artykułu.
- komentarz wstępny;
- komentarze do funkcji.
Komentarz wstępny.
Po włączeniu pliku z kodem źródłowym możemy spotkać się z komentarzem wstępnym. Komentarz taki wstawiamy na początku naszego kodu źródłowego i zamieszczamy w nim informacje ogólne. Na poniższym listingu zamieściłem wzór przykładowego komentarza wstępnego:
/******************************************************************************** * @file ... * @brief ... * @author ... * @version ... * @date ... * @pre ... * @warning ... * @copyright ... * @details ... *******************************************************************************/
W zamieszczonym komentarzu znajdują się wyrazy poprzedzone znakiem @. Takie struktury nazywamy tagami, które pomagają przy identyfikowaniu oraz dokumentowaniu kodu.
Opis tagów występujących w przykładzie:
• @file – wskazuje nazwę pliku źródłowego lub nagłówkowego;
• @brief – wskazuje na skrócony opis zawartości pliku;
• @author – wskazuje autora pliku. Możliwe jest umieszczenie kilku takich tagów w celu wskazania grupy autorów;
• @version – wskazuje wersje pliku. Metodologii zapisu wersji jest kilka. Osobiście preferuję format “v5.2.12”;
• @data – wskazuje datę.Osobiście preferuję zamieszczać datę rozpoczęcia oraz datę ostatniej modyfikacji;
• @pre – wskazuje na opis warunków wstępnych, które na przykład trzeba spełnić przed zastosowaniem pliku;
• @warning – wskazuje na opis komunikatów ostrzegawczych w przypadku zastosowania pliku;
• @copyright – wskazuje do kogo należą prawa autorskie do pliku;
• @details – wskazuje na szczegółowy opis pliku.
Na poniższym listingu znajduje się uzupełniony przykładowy komentarz wstępny.
/******************************************************************************** * @file communication_protocol_uC_db.h * @brief This file contain specific functions for exchange data frame. * @author Dominik Bednarski * @version v4.2.13 * @date 2018-01-01 : 2018-04-07 * @pre First initialize function init_communication_protocol() from communication_protocol_general_db.h file * @warning Do not use the "send ()" function before initializing data * @copyright Freeware License * @details Można opisać na przykład kroki korzystania z bliblioteki *******************************************************************************/
Komentarz do funkcji.
Drugim ważniejszym z mojego punktu widzenia jest komentarz, który umieszcza się tuż nad funkcją. Tego typu komentarze mają na celu szybkie wprowadzenie co dana funkcja wykona, jakie wartości zwraca oraz jakie argumenty przyjmuje. Przykładowy wzór komentarza został zamieszczony na poniższym listingu.
/********************************************************************************* * @brief ... * @param[in] ... * @param[out] ... * @param[in/out] ... * @return ... *********************************************************************************/
Podobnie jak poprzednio użyte zostały tagi. W przypadku wykorzystywania tagów “@param[…]” należy zwrócić uwagę na kolejność argumentów w funkcji. Pierwszy parametr w komentarzu odpowiada pierwszemu argumentowi w funkcji itd.
Opis tagów występujących w przykładzie:
• @brief – wskazuje na skrócony opis zawartości pliku;
• @param[in] – wskazuje na nazwę parametru wejściowego funkcji. Argument ten może być jedynie odczytywany;
• @param[out] – wskazuje na nazwę parametru wyjściowego funkcji. Do tego argumentu można przypisać wartość. Taka możliwość da się uzyskać w przypadku wykorzystania wskaźników czy tablic.;
• @param[in/out] – wskazuje na nazwę parametru wejściowo-wyjściowego funkcji. Argument ten może być zarówno odczytywany oraz może zostać przypisana mu wartość;
• @return – wskazuje na wartość, którą zwraca funkcja.
Na poniższym listingu znajduje się uzupełniony przykładowy komentarz do funkcji z przykładową funkcją.
/*********************************************************************************
* @brief This function add 2 units to the circle radius
* @param[in] x Position x of the center of the wheel in the Cartesian system
* @param[in] y Position y of the center of the wheel in the Cartesian system
* @param[out] d Diameter of the circle
* @param[in/out] r Radius of the circle
* @return This function returns 1 when the operation succeeded or returns -1 when the operation failed
*********************************************************************************/
int resize_circle(int x, int y, int *d, int *r)
{
if((*r)<0)
{
return -1;
}
x=x;
y=y;
*r=(*r)+2;
*d=2*(*r);
return 1;
}
/*>*/
Na koniec
warto jeszcze wspomnieć, że taka forma opisywania plików z kodem jest wspierana przez programy, które automatycznie generują dokumentację. Po zapoznaniu się z kolejnymi tagami oraz z innymi zasadami edycji tekstu dla takich programów, możemy w bardzo szybki sposób stworzyć profesjonalną dokumentację.