Komentarz (informatyka)

Komentarz – fragment kodu źródłowego, którego jedynym celem istnienia jest informowanie o czymś osoby czytającej źródła, a który nie ma żadnego wpływu na program – i jest zazwyczaj przez kompilator czy też interpreter pomijany.

Komentarz to typowy lukier składniowy.

Zasady stosowania komentarzy

Istnieją różne szkoły pisania komentarzy – od jednej skrajności, mówiącej, że z komentarzy powinno się móc wywnioskować wszystko co program robi, bez oglądania reszty źródeł, do drugiej, mówiącej, że jeśli kod nie jest oczywisty bez komentarzy, to jest to zły kod, a komentarze są właściwie zbędne[1].

Generalnie jednak wśród dobrych programistów panuje zgoda, iż jeśli pisze się komentarz, to komentowany powinien być powód, dla którego kod robi to, co robi, lub został napisany tak, a nie inaczej; nie powinien natomiast opisywać tego, co można z łatwością wyczytać – winien opisywać rzeczy, które nie są widoczne na pierwszy rzut oka patrząc na dany kawałek źródeł. Komentarz również nie powinien być błędny, gdyż powoduje to problemy podczas sprawdzania i konserwacji kodu. Nie powinno się również używać komentarzy do prowadzenia notatek, a jeśli już jego prowadzenie jest potrzebne ze względu na długie tworzenie kodu komentarze powinno się usunąć po uzupełnieniu programu[1].

Właściwość komentarzy polegająca na ich „niewidzialności” z punktu widzenia kompilatora jest szeroko wykorzystywana jako metoda rozszerzania właściwości języka. W sekcjach stanowiących komentarze zapisywane są dyrektywy dla kompilatora (pascal[2][3]), treści dla parserów tworzących dokumentacje, czy wręcz całe procedury (JavaScript wewnątrz HTML[4][5]).

Rodzaje komentarzy

Podział komentarzy w językach programowania można dokonać na podstawie różnych kryteriów:

  • podział ze względu na sposób traktowania komentarzy przez translator
  • podział ze względu na składnię.

Podział ze względu na interpretację

Komentarz (wraz ze znakami wydzielającymi komentarz z kodu źródłowego) mogą być traktowane przez translator:

  • tak, jakby ich nie było, jako znak pusty (oznacza to możliwość wstawienia komentarza wewnątrz literału, np. wh{pętla}ile, przy czym napis ten przez translator zostanie uznany za napis while;
  • tak, jak odstęp, np. tak jak spację, np. while{początek pętli}a<b do, komentarz traktowany jak spacja oddzieli słowo kluczowe while od identyfikatora a,;
  • tak, jak instrukcja pusta, np. REM w Basic-u[6][7], choć komentarz jest ignorowany, to poprzedzony etykietą umożliwia skok do tego miejsca w programie;
  • w inny określony przez implementację sposób.

Podział ze względu na składnię

Ze względu na składnię komentarze dzieli się na:

  • blokowe,
  • liniowe,
    • obejmujące całą linię,
    • obejmujące linię od określonego znaku/znaków do końca linii,
  • inne, specjalne.

Komentarze blokowe charakteryzują się tym, że mają znak lub znaki otwierające komentarz i znak lub znaki zamykające komentarz, np. w języku C[8][9][10]: znaki otwierające /* i znaki zamykające */. Daje to możliwość:

  • umieszczania komentarzy wewnątrz linii kodu źródłowego (patrz wyżej);
  • tworzenia komentarzy składających się z wielu linii tekstu bez konieczności poprzedzania każdej linii znakiem komentarza.

Komentarze liniowe to komentarze, które rozpoczynają się od określonego znaku/znaków, a kończą znakiem/znakami końca linii (np. znakiem o kodzie ASCII 13 lub parą znaków 13 i 10, albo innymi przyjętymi w danym systemie). Tworzenie komentarzy składających się z kilku linii wymaga poprzedzania wszystkich linii tekstu znakami komentarza. Rozróżnić można dwa przypadki:

  • komentarzem musi być cała linia tekstu,
  • komentarz rozpoczyna się w dowolnym miejscu linii kodu źródłowego od określonego znaku/znaków, a końcem komentarza jest koniec linii.

Przykład w języku Basic[6][7]:

 10 REM To jest komentarz składający się z całej linii kodu źródłowego
 20 LET A=1 ' A to komentarz od znaku ' do końca linii

Zestawienie komentarzy

Komentarze w językach programowania

Język programowaniaRodzajSkładnia
Assembler[11], AutoLISPliniowy; komentarz
ALGOL 60[12]blokowybegin comment [komentarz]; end;
blokowycomment [komentarz];
blokowyend komentarz <; lub end lub else>
inny: w deklaracji i wywołaniu procedurynazwa_proc(par1) [komentarz_2]:(par2) [komentarz_3]:(par3) ... [komentarz_n]:(par_n);
Bashliniowy# [komentarz]
Basic[6][7], Visual Basic[13][14]liniowy[nr linii] REM [komentarz]
liniowy[nr linii] [instrukcja] ' [komentarz]
PL/I[15][16], PL/M[17][18]blokowy/* [komentarz] */
C[8][9][10], C++[10], C#[19]blokowy/* [komentarz] */
liniowy// [komentarz]
Clipper[20]liniowy1)* [komentarz]
liniowy&& [komentarz]
liniowy// [komentarz]
DBase[21][22]liniowy[instrukcja] && [komentarz]
liniowy1)* [komentarz]
Fortran 77[23]liniowy1)C [komentarz]
liniowy1)* [komentarz]
Forth[24][25]blokowy( [komentarz] )
Icon[26], Perl[27]liniowy[instrukcje] # [komentarz]
Jean[28][29]liniowy1)* [komentarz]
Logo[30]liniowy1); [komentarz]
Makefile (Borland)[3]liniowy[instrukcje] # [komentarz]
Modula 2[31]blokowy(* [komentarz] *)
Pascal[2][3]blokowy{ [komentarz] }
blokowy(* [komentarz] *)
Prolog[32]liniowy% komentarz
blokowy/* [komentarz] */
PHP[33]liniowy# [komentarz]
liniowy// [komentarz]
blokowy/* [komentarz] */
Python[34]liniowy[instrukcje] # [komentarz]
blokowy""" [komentarz] """
Simula 67[35]blokowycomment [komentarz];
Snobol[36]liniowy1)* [komentarz]
1) Znak komentarza musi być pierwszym znakiem w linii kodu:

Zestawienie według rodzajów

rodzajtyp, uwagiskładniajęzyki programowania
liniowycała linia, znak komentarza musi być pierwszym znakiem* komentarzClipper[20], Cobol[37], DBase[21][22], Fortran 77[23], Snobol[36], Jean[28][29]
C komentarzFortran 77[23]
; komentarzLogo[30]
może być poprzedzony wyłącznie określoną jednostką leksykalną[nr_linii] REM komentarzBasic[6][7], Visual Basic[13][14]
może być poprzedzony instrukcją/instrukcjami[instr.] ' komentarzBasic (niektóre dialekty), Visual Basic[13][14]
[instr.] ; komentarzAsembler[11], AutoLISP
[instr.] // komentarzC++[10], Clipper[20], JavaScript
[instr.] && komentarzClipper[20], DBase[21][22]
[instr.] % komentarzProlog[32]
[instr.] # komentarzIcon[26], Perl[27], Makefile (Borland)[3], Python
[instr.] -- komentarzSQL
blokowyo zapisie swobodnym{ komentarz }Pascal[2][3]
(* komentarz *)Pascal, Modula 2[31], ML, Mathematica, Applescript, Ocaml
( komentarz )Forth[24][25]
/* komentarz */C[8][9][10], C++[10], C♯, Java, JavaScript[4][5], PHP[38], SQL, Visual Prolog, CSS, PL/I[15][16], PL/M[17][18], Prolog[32]
""" komentarz """Python[34]
instrukcja; comment komentarz; instrukcje ...ALGOL 60[12], Simula 67[35]
  • begin comment komentarz; instrukcje ... end;
  • end komentarz <; | end | else>
ALGOL 60[12]
<!--komentarz-->Wiki, HTML, XML[a]
inneopis parametrów podprogramównazwa_proc(par1) komentarz_2:(par2) komentarz_3:(par3) ... komentarz_n(par_n);ALGOL[12] – można stosować w deklaracji i wywołaniu procedury

Przypisy

  1. ↑ a b Stephan Dewhurst: C++ Kruczki i fortele w programowaniu. Gliwice: Helion, 2004, s. 13. ISBN 83-7361-346-3.
  2. ↑ a b c Michał Iglewski, Jan Madey, Stanisław Matwin: Pascal. Język wzorcowy – Pascal 360. Wyd. wydanie trzecie – zmienione. Warszawa: Wydawnictwa Naukowo-Techniczne, 1984, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-85060-53-7. ISSN 0867-6011. (pol.)
  3. ↑ a b c d e Andrzej Marciniak: Borland Pascal 7.0. Poznań: Nakom, 1994, seria: Biblioteka Użytkownika Mikrokomputerów. ISBN 83-85060-53-7. ISSN 0867-6011. (pol.)
  4. ↑ a b Wojciech Romowicz: HTML i JavaScript. HELION, 1998. ISBN 83-7197-046-3. (pol.)
  5. ↑ a b Kurs języka JavaScript (pol.). Poradnik Webmastera. [dostęp 2011-02-09]. [zarchiwizowane z tego adresu (2011-09-27)].
  6. ↑ a b c d Zbigniew Czech, Krzysztof Nałęcki, Stanisław Wołek: Programowanie w języku BASIC. Wyd. drugie uzupełnione. Warszawa: Wydawnictwa Naukowo-Techniczne, 1985. ISBN 83-204-0776-1. (pol.)
  7. ↑ a b c d Wacław Iszkowski: Nauka programowania w języku BASIC dla początkujących. Warszawa: Wydawnictwa Naukowo-Techniczne, 1987, seria: Mikrokomputery. ISBN 83-204-0834-2. (pol.)
  8. ↑ a b c Brian W. Kernighan, Dennis M. Ritche: Język C. Warszawa: Wydawnictwa Naukowo-Techniczne, 1988, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-204-1067-3. (pol.)
  9. ↑ a b c Jan Bielecki: Turbo C z grafiką na IBM PC. Warszawa: Wydawnictwa Naukowo-Techniczne, 1990, seria: Mikrokomputery. ISBN 83-204-1101-7. (pol.)
  10. ↑ a b c d e f Jan Bielecki: Od C do C++, programowanie obiektowe w języku C. Warszawa: Wydawnictwa Naukowo-Techniczne, 1990. ISBN 83-204-1332-X. (pol.)
  11. ↑ a b Leo J. Scanlon, tłumaczenie: Lucyna Stanikowska: Assembler 8086/8088/80286. Warszawa: Intersoftland, 1992. ISBN 83-85515-03-8. (pol.)
  12. ↑ a b c d Joanna Jonkisz, Jan Makuch, Stanisław Starzak: Programowanie w językach Algol 60 i Fortran 1900. Łódź: Wydawnictwo Politechniki Łódzkiej, Politechnika Łódzka, Ośrodek Elektronicznej Techniki Obliczeniowej, 1982, seria: Skrypty dla szkół wyższych. (pol.)
  13. ↑ a b c Podręcznik Visual Basic na Wikibooks
  14. ↑ a b c John Walkenbach: Excel 2003 PL. Programowanie w VBA.. HELION, 2004. ISBN 837361-504-0. (pol.)
  15. ↑ a b Jan Bielecki: Rozszerzony PL/I i JCL w systemie OS/RIAD. Warszawa: Państwowe Wydawnictwo Naukowe, 1986, seria: Biblioteka Informatyki. ISBN 83-01-06146-4. (pol.)
  16. ↑ a b M. I. Auguston i inni: Programowanie w języku PL/1 OS JS. Warszawa: Państwowe Wydawnictwo Naukowe, 1988. ISBN 83-01-07463-9. (pol.)
  17. ↑ a b Jan Bielecki: PL/M język programowania mikroprocesorów. Wyd. wydanie drugie uzupełnione. Warszawa: Wydawnictwa Komunikacji i Łączności, 1987, seria: Elektronizacja. zeszyt 25. (pol.)
  18. ↑ a b Jan Bielecki: System operacyjny ISIS-II. Warszawa: Wydawnictwa Naukowo-Techniczne, 1987, seria: Mikrokomputery. ISBN 83-204-0893-8. (pol.)
  19. ↑ Komentarze w języku C# i środowisku Visual Studio – kurs.aspnetmvc.pl, kurs.aspnetmvc.pl [dostęp 2018-07-03] (ang.).
  20. ↑ a b c d Wojciech Rogowski, Arkadiusz Serodziński: Clipper 5.0. Warszawa: Wydawnictwo PLJ, 1991. ISBN 83-85190-20-1. (pol.)
  21. ↑ a b c Tadeusz Mykowiecki: dBase, FoxBase, bazy danych. Warszawa: Wydawnictwa Naukowo-Techniczne, 1992. ISBN 83-204-1345-1. (pol.)
  22. ↑ a b c Piotr J. Jasiński, Zbigniew Królikowski, Jacek Szulczyński: Mikrokomputerowe bazy danych z programowaniem w dBase IV. Warszawa: Poznań, 1992, seria: Biblioteka Użytkownika Mikrokomputerów tom 7. ISBN 83-85060-44-8. ISSN 0867-6011. (pol.)
  23. ↑ a b c Ryszard K. Kott, Krzysztof Walczak: Programowanie w języku Fortran 77. Warszawa: Wydawnictwa Naukowo-Techniczne, 1991. ISBN 83-204-1362-1. (pol.)
  24. ↑ a b Jan Bielecki: Język FORTH. Warszawa: Wydawnictwa Naukowo-Techniczne, 1988, seria: Mikrokomputery. ISBN 83-204-0930-6. (pol.)
  25. ↑ a b Jan Ruszczyc: Poznajemy FORTH. Warszawa: SOETO, 1987, seria: Informatyka mikrokomputerowa. (pol.)
  26. ↑ a b Ralph E. Griswold, Madge T. Griswold: Icon. Warszawa: Wydawnictwa Naukowo-Techniczne, 1987, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-204-0871-7. (pol.)
  27. ↑ a b Podręcznik języka Perl na Wikibooks
  28. ↑ a b Jerzy Bettek, Bronisław Rudak, Barbara Rudakowa: Język konwersacyjny JEAN. Wrocław: Wydawnictwo Politechniki Wrocławskiej, 1975, seria: Skrypt wydany w serii Biblioteka WASC. (pol.)
  29. ↑ a b Kazimierz Orlicz: Język konwersacyjny JEAN z elementami programowania w Fortranie. Wrocław: Wydawnictwo Politechniki Wrocławskiej, 1977, seria: Skrypt wydany w serii Biblioteka WASC. (pol.)
  30. ↑ a b Stanisław Waligórski: LOGO na Sinclair Spectrum. Instytut Wydawniczy Związków Zawodowych, seria: Seria 12+12=102. (pol.)
  31. ↑ a b Niklaus Wirth: Modula 2. Warszawa: Wydawnictwa Naukowo-Techniczne, 1987, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-204-0828-8. ISSN 0867-6011. (pol.)
  32. ↑ a b c Janusz Szajna, Marian Adamski, Tomasz Kozłowski: Turbo Prolog. Programowanie w języku logiki.. Warszawa: Wydawnictwa Naukowo-Techniczne, 1991, seria: Mikrokomputery. ISBN 83-204-1395-8. (pol.)
  33. ↑ PHP: Komentarze – Manual. php.net. [zarchiwizowane z tego adresu (2013-12-14)]. (pol.)
  34. ↑ a b Writing Comments in Python (ang.)
  35. ↑ a b Hanna Oktaba, Wiesław Ratajczak: Simula 67. Warszawa: Wydawnictwa Naukowo-Techniczne, 1990, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-204-0128-3. (pol.)
  36. ↑ a b Paweł Gizbert-Studnicki, Jerzy Kaczmarczuk: Snobol4. Warszawa: Wydawnictwa Naukowo-Techniczne, 1984, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-204-0546-7. (pol.)
  37. ↑ Eugeniusz Kurzydrem, Andrzej Macieliński, Urszula Szmidt, Eugeniusz Więcek: COBOL. Język programowania.. Wyd. drugie. Warszawa: Państwowe Wydawnictwo Ekonomiczne, 1978. (pol.)
  38. ↑ Podręcznik języka PHP na Wikibooks

Bibliografia

  • Michael Marcotty, Henry Ledgord, tłumaczenie: Krystyna Jerzykiewicz: W kręgu języków programowania. Warszawa: Wydawnictwa Naukowo-Techniczne, 1980, seria: Biblioteka Inżynierii Oprogramowania. ISBN 83-204-1342-7. (pol.)
  • John E. Nicholls: Struktura języków programowania. Warszawa: Wydawnictwa Naukowo-Techniczne, 1980, seria: Informatyka. ISBN 83-204-0246-8. (pol.)

Uwagi

  1. ↑ Podane tu przykłady nie są językami programowania

Zobacz też