У програмуванні, коментар це зрозуміла для програміста анотація в коді комп’ютерної програми. Їх пишуть для того щоб зробити сирцевий код більш зрозумілим, вони ігноруються при компіляції й інтерпретації.Source code can be divided into program code (which consists of machine-translatable instructions); and comments (which include human-readable notes and other kinds of annotations in support of the program code).For purposes of this article, programming language comments are treated as indistinct from comments that appear in markup languages, configuration files and other similar contexts. Запис коментарів сильно відрізняється в залежності від мови програмування.
Їх пишуть не тільки для роз’яснення вихідного коду програмістам, коментарі також обробляють різними способами для створення окремої документації на базі вихідного коду за допомогою генераторів документації, або використовують для інтеграції з системою контролю версій чи іншим інструментами програмування.
Щоб не було зловживань з використанням коментарів, у багатьох мовах для них виділені окремі розділи в рекомендаціях з оформлення коду.
Огляд Коментарі зазвичай мають два формати: багаторядкові і однорядкові.Dixit, J.B. (2003).
Багаторядкові коментарі у коді обмежуються роздільниками на початку і в кінці, всі символи всередині вважаються коментарем. Деякі мови програмування (наприклад MATLAB) дозволяють створювати вкладені коментарі, інші ні (наприклад Java).Higham, Desmond (2005). Vermeulen, Al (2000). "Using the right comment in Java" .
Однорядкові коментарі починаються з роздільника, весь текст у рядку що йде після нього вважається коментарем.
Деякі мови програмування використовують обидва типи коментарів, але з різними роздільниками. Для прикладу, C++ має багаторядкові коментарі, які починаються з /* а закінчуються */ і однорядкові для яких використовується роздільник //. Інші мови підтримують тільки один тип коментарів. Для прикладу, Ada підтримують тільки однорядкові коментарі, роздільник --.
Використання Про те як найкраще використовувати коментарі досі точаться дискусії, учасники цих дискусій пропонуються різні підходи, а інколи навіть протилежні.W. R., Dietrich (2003). Keyes, Jessica (2003). Через те що є багато способів коментування коду можна зустріти поради, які суперечать одна одній.
Планування і перевірка коду Коментарі можуть бути використані для написання програми на псевдокоді і в подальшому на цій базі написання реального коду./* loop backwards through all elements returned by the server (they should be processed chronologically)*/ for (i = (numElementsReturned - 1); i >= 0; i--){ /* process each element's data */ updatePattern(i, returnedElements[i]); }Таке використання коментарів полегшує роботу тому хто робить перегляд коду, бо видно що планувалося зробити і що є насправді. Але такий метод коментування породжує очевидні коментарі, які засмічують код.
Опис коду Коментарі можуть бути використанні для узагальнення чи пояснення намірів розробника, тобто описувати логіку програми. Прихильники даного підходу вважають поганою практикою писати коментарі безпосередньо до рядків коду, а також якщо саме код потребує додаткових пояснень це ознака занадто складного чи неякісного коду.
У коментарях також можна пояснювати виняткові ситуації (наприклад, код який не вписується в узгоджені правила розробки). Такі коментарі часто зустрічаються на ранніх етапах розробки чи зневадження. Для прикладу:' Second variable dim because of server errors produced when reuse form data. No ' documentation available on server behavior issue, so just coding around it. vtx = server.mappath("local settings")
Опис алгоритму Іноді вихідний код містить специфічне рішення конкретної проблеми. У таких випадках коментарі можуть містити пояснення чому був вибраний саме такий розв'язок. Такі пояснення можуть включати в себе схеми і формальні математичні докази. Це може бути пояснення коду, а не роз'яснення того що ви хотіли зробити; для підтримки бази коду вони можуть відігравати вирішальну роль. Такі коментарі особливо рекомендується використовувати у вузькоспеціалізованих проблемних галузях або для спосіб оптимізації чи конструкцій, які рідко використовуються.Spinellis, Diomidis (2003).
Для прикладу, тут програміст в коментарі може пояснити чому він вибрав сортування вставками замість звичного quicksort, хоч перший, теоретично, повільніший ніж другий. Це можна було б описати так: list = [f (b), f (b), f (c), f (d), f (a), ...]; // Need a stable sort. Besides, the performance really does not matter. insertion_sort (list);
Включення вмісту Логотипи, діаграми та блок-схеми на базі ASCII графіки можуть бути вставлені в вихідний код, у вигляді коментаря."CodePlotter 1.6 - Add and edit diagrams in your code with this 'Visio-like' tool" . Також у них можна розмістити інформацію про авторське право. Бінарна інформація теж може бути записана у коментарях, завдяки перетворенню binary-to-text, хоча це рідко практикуються.
Наведений далі код це фрагмент простої ASCII діаграми, яка зображує процес для скрипту системного адміністратора який міститься в Windows Script File виконається під Windows Script Host. Хоча в коді дана діаграма маркована як коментар, сама схема насправді буде відображатися в XML CDATA секції, яка технічно відрізняється від коментарів, але може виконувати аналогічну функцію.Niederst, Jennifer (2006). <!-- begin: wsf_resource_nodes --> <resource id="ProcessDiagram000"> <![CDATA[ HostApp (Main_process)
V script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
V mru.ini (mru_history) ]]> </resyntaxhighlight>
Метадані Коментарі в комп'ютерній програмі можуть містити метадані про файл програми.
Зокрема, багато розробників які супроводжують ПЗ додають вступну довідку (в коментарях), для людей які планують читати вихідний код чи тим хто планує відправляти свої покращення.
Відлагоджування Часто розробники записують у коментарі сніпети, які місця логіку для зневадження програми ці коментарі можна у будь-який момент розкоментувати і отримати інформацію про роботу програми. Також програмісти практикують коментування код при пошуку ділянки, яка некоректно працює. Приклад, відлагодження коду шляхом коментування: if (opt.equals ("e")) opt_enabled = true; /* if (opt.equals ("d")) opt_debug = true; // */ //* if (opt.equals ("v")) opt_verbose = true; // */
Автоматична генерація документації
Інструменти програмування іноді зберігають документацію і метадані в коментарях.See e.g., Wynne-Powell, Rod (2008). Вони можуть вказувати на включення заголовних файлів, інформацію про режим підсвітки тексту,Lamb, Linda (1998). чи версію файлу.See e.g., Berlin, Daniel (2006). Такі функціональні коментарі зазвичай наживають анотацією. Ведення документації у коментарях вихідного коду розглядається, як один із способів, щоб спростити процес підготовки документації, а також збільшити ймовірність того, що документація буде постійно оновлюватися зі змінами в коді.Ambler, Scott (2004).
Програми генератори документації існують у багатьох мовах, наприклад: Java має Javadoc, D Ddoc, Doxygen генерує документації для таких мов C, C++, Java, IDL, а PHPDoc для PHP.
Приклади
Ada Мова програмування Ada використовує '--' для позначення початку однорядкового коментаря.
Приклад: -- the air traffic controller task takes requests for takeoff and landing task type Controller (My_Runway: Runway_Access) is -- task entries for synchronous message passing entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access); entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access); end Controller;
AppleScript Наступний код AppleScript показує два типи коментарів, які доступні у цій мові.(* This program displays a greeting. *) on greet(myGreeting) display dialog myGreeting & " world!" end greet
-- Show the greeting greet("Hello")
BASIC Фрагмент коду на BASIC повністю консольна програма, в якій використовується ключове слово REM ("REMark"), щоб додавати коментарі, які описують те, що робить програма.10 REM This BASIC program shows the use of the PRINT and GOTO statements. 15 REM It fills the screen with the phrase "HELLO" 20 PRINT "HELLO" 30 GOTO 20Весь текст після символу ' (апостроф) вважається коментарем у Microsoft BASICs, включно QuickBasic, Qbasic, Visual Basic, Visual Basic .NET і VBScript - і похідних таких як FreeBASIC і Gambas.
Приклад на Visual Basic .NET:Public Class Form1 Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click ' The following code is executed when the user ' clicks the button in the program's window.
MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting End Sub End Class
C Цей фрагмент коду на C демонструє використання багаторядкових коментарів, щоб описати призначення умовного оператора. Коментар пояснює основні терміни і поняття, і включає підпис програмістом, який є автором коду. /* * Check if we are over our maximum process limit, but be sure to * exclude root. This is needed to make it possible for login and * friends to set the per-user process limit to something lower * than the amount of processes root is running. -- Rik */ if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE)) goto bad_fork_free;У C99, також стало можливо використовувати // синтаксис від C ++, для написання однорядкових коментарів.
ColdFusion ColdFusion використовує коментарі схожі до HTML коментарів, але замість двох дефісів, він використовує три. Ці коментарі зчитуються рушієм ColdFusion, а також не відображаються у браузері. <!--- This prints "Hello World" to the browser. ---> <cfoutput> Hello World<br /> </cfoutput>
Fortran IV Цей код на Fortran IV демонструє використання коментарів у цій мові.C C Lines that begin with 'C' (in the first or 'comment' column) are comments C WRITE (6,10) 10 FORMAT(12H HELLO WORLD) END
Fortran 90 Цей код на Fortran демонструє використання коментарів у цій мові.!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * !* All characters after an exclamation mark are considered as comments * !* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * program comment_test print '(A)', 'Hello world' ! Fortran 90 introduced the option for inline comments. end program
Haskell Однорядкові коментарі в Haskell починаються з '--' (два мінуси), а багаторядкові коментарі починаються з '{-' та закінчуються '-}'.{- this is a comment on more lines -} -- and this is a comment on one line putStrLn "Wikipedia"Haskell також підтримує literate programming метод коментарів який відомий як "Bird Style ". У такому коді всі рядки які починаються з > інтерпретуються, всі інші коментарі. Ще одна вимога полягає в тому, що ви завжди маєте залишати порожній рядок до і після блоку коду:In Bird-style you have to leave a blank before the code.
> fact :: Integer -> Integer > fact 0 = 1 > fact n = n * fact (n-1)
And you have to leave a blank line after the code as well.
Java У цьому фрагменті коду на Java показаний запис багаторядкових коментарів, для опису методу setToolTipText. Стиль сумісний з стандартом Sun Microsystems Javadoc. Коментар призначений для зчитування процесором Javadoc. /** * Registers the text to display in a tool tip. The text * displays when the cursor lingers over the component.
* @param text the string to display. If the text is null, * the tool tip is turned off for this component. */ public void setToolTipText(String text) {
JavaScript JavaScript використовує // для однорядкових коментарів, /* */ для багаторядкових.// A single line JavaScript comment var iNum = 100; var iTwo = 2; // A comment at the end of line /* multi-line JavaScript comment */
MATLAB