CKTIS / C
comments and documentation — pojęcie C23
C obsługuje komentarze blokowe `/* ... */` i wierszowe `// ...`; komentarze są usuwane we wczesnej fazie translacji, a bloków nie wolno zagnieżdżać. Dokumentacja powinna opisywać kontrakt i przyczynę ograniczenia, nie powtarzać oczywistego kodu.
Wersja: C23
Składnia
comments and documentationC obsługuje komentarze blokowe /* ... */ i wierszowe // ...; komentarze są usuwane we wczesnej fazie translacji, a bloków nie wolno zagnieżdżać. Dokumentacja powinna opisywać kontrakt i przyczynę ograniczenia, nie powtarzać oczywistego kodu.
W praktyce komentarz nad funkcją powinien podać własność wskaźników, jednostki rozmiaru, znaczenie wyniku i warunki błędu. Krótki komentarz wewnątrz algorytmu jest użyteczny, gdy wyjaśnia nieoczywisty niezmiennik albo powód kolejności operacji.
Sekwencja /* wewnątrz komentarza blokowego nie otwiera nowego poziomu, więc pierwsze */ kończy całość i może odsłonić przypadkowy kod. Makro nie może niezawodnie „zakomentować” dowolnego fragmentu; do wyłączania kodu użyj kontrolowanego #if 0 i pamiętaj, że tekst nadal musi być poprawny dla preprocesora.
Przykłady
#include <stdio.h>
int main(void) {
/* A block comment cannot be nested. */
int value = 6; // The line comment ends at the newline.
printf("%d\n", value + 1);
return 0;
}
Wynik
7
C obsługuje komentarze blokowe `/* ... */` i wierszowe `// ...`; komentarze są usuwane we wczesnej fazie translacji, a bloków nie wolno zagnieżdżać. Dokumentacja powinna opisywać kontrakt i przyczynę ograniczenia, nie powtarzać oczywistego kodu.