Komentáře - vysvětlení ke zdrojovému kódu programu , umístěné přímo v komentovaném kódu. Syntaxe komentářů je definována programovacím jazykem . Z pohledu překladače nebo interpreta jsou komentáře součástí textu programu, který neovlivňuje jeho sémantiku. Komentáře nemají žádný vliv na výsledek kompilace programu ani jeho interpretaci. Kromě zdrojového kódu programu se komentáře používají také ve značkovacích jazycích a jazycích popisu .
Většina odborníků souhlasí s tím, že komentáře by měly vysvětlovat záměr programátora , nikoli kód; to, co lze vyjádřit v programovacím jazyce, by se nemělo komentovat – zejména by se měly používat smysluplné názvy pro proměnné, funkce, třídy, metody a další entity (viz Konvence pojmenování ), program rozdělit na snadno srozumitelné části, usilovat o to, aby struktura tříd a databázová struktura byla co nejsrozumitelnější a nejtransparentnější atd. Existuje dokonce názor (dodržuje se v extrémním programování a některých dalších flexibilních programovacích metodologiích ), že pokud jsou pro pochopení programu vyžadovány komentáře, znamená to, že je to špatně napsané.
Koncept gramotného programování trvá na zahrnutí tak podrobných a promyšlených komentářů do textu programu, aby se stal zdrojovým textem nejen pro spustitelný kód, ale i pro doprovodnou dokumentaci .
Komentáře se často používají k dočasné deaktivaci části kódu. V C a C++ , některé[ kdo? ] doporučuje používat pro stejný účel direktivy preprocesoru ( #if 0... ).#endif
Z hlediska syntaxe existují dva druhy komentářů. Víceřádkový komentář může mít libovolnou délku a je označen speciálními znaky na začátku a konci (například /* */). Některé jazyky umožňují vnořování víceřádkových komentářů, jiné ne.
Jednořádkový komentář je označen speciálním znakem na začátku (např //. ) a pokračuje až do konce řádku. Normálně mohou být jednořádkové komentáře vnořeny do jiných, jednořádkových nebo víceřádkových komentářů. Záznamové metody lze prokládat, z hlediska sémantiky jsou stejné.
Jiný druh komentářů - anotace - se používá v náčrtech důkazů správnosti programů. Takové komentáře popisují stav počítače, když program během provádění dosáhne bodu, kde se nachází komentář. Anotovaný program se nazývá anotovaný program .
Speciálně formátované komentáře (tzv. dokumentační komentáře ) se používají k automatickému vytváření dokumentace , především pro knihovny funkcí nebo tříd . K tomu slouží generátory dokumentace , např. javadoc [1] pro jazyk Java , phpDocumentor pro PHP [2] , doxygen [3] pro C a C++ atd.
Komentáře k dokumentaci jsou obvykle formátovány jako víceřádkové komentáře ve stylu C. V každém případě musí komentář předcházet dokumentovanému prvku. První znak v komentáři (a na začátku řádků komentáře) musí být *. Bloky jsou odděleny prázdnými řádky.
Příklad komentáře k dokumentaci
/** * Název objektu nebo krátký popis * * Rozšířený popis * * Hodnota @descriptor_name * @return data_type */V některých programovacích prostředích (např. Eclipse , NetBeans , Python , Visual Studio ) se komentáře k dokumentu používají jako interaktivní nápověda k rozhraní tříd a funkcí.
Během překladu jsou komentáře rozpoznány ve fázi lexikální analýzy (a jsou tedy považovány za tokeny ). Rozpoznávání ve fázi předběžného zpracování je drahé a dokonce plné chyb; zahrnout komentáře do syntaktických diagramů je téměř nemožné.
Komentáře by měl kompilátor ignorovat, ale v praxi tomu tak vždy není. Některé speciální příkazy pro překladatele, které jsou vysoce závislé na implementaci programovacího jazyka, jsou často formátovány jako komentáře.
Například v dialektu Turbo Pascal se pragmas {$I-}a {$I+}používají k deaktivaci a povolení standardní kontroly chyb I/O. Podobné speciální komentáře se používají ve značkovacím jazyce HTML k označení typu dokumentu SGML , "escaping" stylů a skriptování v JavaScriptu a VBScriptu :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"> … < TYP STYLU = "text/css" > <! -- … popis stylů -- > </ STYLE > … < SCRIPT TYPE = "text/javascript" > <!-- skrýt obsah skriptu ze starších prohlížečů … kód skriptu JavaScript // konec skrytého obsahu --> < / SCRIPT >Některé komentáře používají programátoři při své práci. Komentáře jako tento jsou zvláště užitečné, když na stejném kódu pracuje více vývojářů. Například komentář TODO se obvykle používá k označení části kódu, kterou programátor nechává nedokončenou, aby se k ní mohl vrátit později. Komentář FIXME označí chybu, která byla nalezena a je rozhodnuto, že bude později opravena. Komentář XXX označuje nalezenou kritickou chybu, bez jejího odstranění nelze v další práci pokračovat.