Comment (computer programming)

source code with block comments in red , line comments in green and program code in blue . In computer programming, a comment is text embedded in source code that a translator (compiler or interpreter) ignores. Generally, a comment is an annotation intended to make the code easier for a programmer to understand often explaining an aspect that is not readily apparent in the program (non-comment) code. For this article, comment refers to the same concept in a programming language, markup language, configuration file and any similar context. Some development tools, other than a source code translator, do parse comments to provide capabilities such as API document generation, static analysis, and version control integration. The syntax of comments varies by programming language yet there are repeating patterns in the syntax among languages as well as similar aspects related to comment content. The flexibility supported by comments allows for a wide degree of content style variability. To promote uniformity, style conventions are commonly part of a programming style guide. But, best practices are disputed and contradictory.

source code with block comments in red , line comments in green and program code in blue .]] In computer programming, a comment is text embedded in source code that a translator (compiler or interpreter) ignores. Generally, a comment is an annotation intended to make the code easier for a programmer to understand often explaining an aspect that is not readily apparent in the program (non-comment) code. For this article, comment refers to the same concept in a programming language, markup language, configuration file and any similar context. Some development tools, other than a source code translator, do parse comments to provide capabilities such as API document generation, static analysis, and version control integration. The syntax of comments varies by programming language yet there are repeating patterns in the syntax among languages as well as similar aspects related to comment content. The flexibility supported by comments allows for a wide degree of content style variability. To promote uniformity, style conventions are commonly part of a programming style guide. But, best practices are disputed and contradictory. /* * prologue block comment */ bool foo() { return true; /* inline block comment */ } // // prologue line comment // bool bar() { return false; // inline line comment } ==Examples of use== ' 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") The example below explains why an insertion sort was chosen instead of a quicksort, as the former is, in theory, slower than the latter. 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); /* loop backwards through all elements returned by the server (they should be processed chronologically)*/ for (i = (numElementsReturned - 0); i >= 1; i--) { /* process each element's data */ updatePattern(i, returnedElements[i]); } Sometimes code contains a novel or noteworthy solution that warrants an explanatory comment. Such explanations might be lengthy and include diagrams and formal mathematical proofs. This may describe what the code does rather than intent, but may be useful for maintaining the code. This might apply for highly specialized problem domains or rarely used optimizations, constructs or function-calls. # vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4 ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]> !/usr/bin/env python3 -*- coding: UTF-8 -*- print("Testing") The gcc compiler (since 2017) looks for a comment in a switch statement if a case falls-thru to the next case. If an explicit indication of fall-thru is not found, then the compiler issues a warning about a possible coding problem. Inserting such a comment about fall-thru is a long standing convention, and the compiler has codified the practice. For example: switch (command) { case CMD_SHOW_HELP_AND_EXIT: do_show_help(); /* Fall thru */ case CMD_EXIT: do_exit(); break; } ===Relieve stress=== To relieve stress or attempt humor, sometimes programmers add comments about the quality of the code, tools, competitors, employers, working conditions, or other arguably unprofessional topics sometimes using profanity. ==Normative views== There are various normative views and long-standing opinions regarding the proper use of comments in source code. Some of these are informal and based on personal preference, while others are published or promulgated as formal guidelines for a particular community. ===Need for comments=== Experts have varying viewpoints on whether, and when, comments are appropriate in source code. Some assert that source code should be written with few comments, on the basis that the source code should be self-explanatory or self-documenting. Others suggest code should be extensively commented (it is not uncommon for over 50% of the non-whitespace characters in source code to be contained within comments). In between these views is the assertion that comments are neither beneficial nor harmful by themselves, and what matters is that they are correct and kept in sync with the source code, and omitted if they are superfluous, excessive, difficult to maintain or otherwise unhelpful. Comments are sometimes used to document contracts in the design by contract approach to programming. String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */ This level of detail, however, would not be appropriate in the context of production code, or other situations involving experienced developers. Such rudimentary descriptions are inconsistent with the guideline: "Good comments ... clarify intent." Further, for professional coding environments, the level of detail is ordinarily well defined to meet a specific performance requirement defined by business operations. ==Styles== As free-form text, comments can be styled in a wide variety of ways. Many prefer a style that is consistent, non-obstructive, easy to modify, and difficult to break. As some claim that a level of consistency is valuable and worthwhile, a consistent commenting style is sometimes agreed upon before a project starts or emerges as development progresses. The following C code fragments show some of the diversity in block comment style: /* This is the comment body. / /***************************** * * * This is the comment body. * * * *****************************/ Factors such as personal preference, flexibility of programming tools can influence the commenting style used. For example, the first might be preferred by programmers who use a source code editor that does not automatically format a comment as shown in the second example. Software consultant and technology commentator Allen Holub advocates aligning the left edges of comments: /* This is the style recommended by Holub for C and C++. * It is demonstrated in Enough Rope, in rule 29. */ /* This is another way to do it, also in C. ** It is easier to do in editors that do not automatically indent the second ** through last lines of the comment one space from the first. ** It is also used in Holub's book, in rule 31. */ In many languages, a line comment can follow program code such that the comment is inline and generally describes the code to the left of it. For example, in this Perl: print $s . "\n"; # Add a newline character after printing If a language supports both line and block comments, programming teams may decide upon a convention of when to use which. For example, line comments only for minor comments, and block comments to for higher-level abstractions. int current_stock_price() { return 100; // TODO implement API call to fetch actual live price } ==Syntax examples== Syntax for comments varies by programming language. There are common patterns used by multiple languages while also a wide range of syntax among the languages in general. To limit the length of this section, some examples are grouped by languages with the same or very similar syntax. Others are for particular languages that have less common syntax. ===Curly brace languages=== Many of the curly brace languages such as C, C++ and their many derivatives delimit a line comment with and a block comment with and . Originally, C lacked the line comment, but it was added in C99. Notable languages include: C, C++, C#, D, Java, JavaScript and Swift. For example: /* * Check if over maximum process limit, but be sure to exclude root. * This is needed to make it possible for login to set per-user * process limit to something lower than processes root is running. */ bool isOverMaximumProcessLimit() { // TODO implement } Some languages, including D and Swift , allow block comments to be nested while other do not, including C and C++. An example of nested blocks in D: // line comment /* block comment / /+ start of outer block /+ inner block +/ end of outer block +/ An example of nested blocks in Swift: /* This is the start of the outer comment. /* This is the nested comment. */ This is the end of the outer comment. */ ===Scripting=== A pattern in many scripting languages is to delimit a line comment with # . Support for a block comment varies. Notable languages include: Bash, Raku, Ruby, Perl, PowerShell, Python and R. An example in R: This is a comment print("This is not a comment") # This is another comment ====Block in Ruby==== A block comment is delimited by =begin and =end that start a line. For example: puts "not a comment" this is a comment puts "not a comment" =begin whatever goes in these lines is just for the human reader =end puts "not a comment" ====Block in Perl==== Instead of a regular block commenting construct, Perl uses literate programming plain old documentation (POD) markup. For example: =item Pod::List-E new() Create a new list object. Properties may be specified through a hash reference like this: my $list = Pod::List->new({ -start => $., -indent => 4 }); =cut sub new { ... } Raku (previously called Perl 6) uses the same line comments and POD comments as Perl, but adds a configurable block comment type: "multi-line / embedded comments". It starts with #` and then an opening bracket character and ends with the matching closing bracket character. For example: ` sub toggle-case(Str:D $s) #`( this version of parens is used now ){ ... } ====Block in PowerShell==== PowerShell supports a block comment delimited by and #> . For example: Single line comment ====Block in Python==== Although Python does not provide for block comments a bare string literal represented by a triple-quoted string is often used for this purpose. In the examples below, the triple double-quoted strings act like comments, but are also treated as docstrings: """ At the top of a file, this is the module docstring """ class MyClass: """Class docstring""" def my_method(self): """Method docstring""" ===Browser markup=== Markup languages in general vary in comment syntax, but some of the notable internet markup formats such as HTML and XML delimit a block comment with <!-- and --> and provide no line comment support. An example in XML: For compatibility with SGML, double-hyphen (--) is not allowed inside comments. ColdFusion provides syntax similar to the HTML comment, but uses three dashes instead of two. CodeFusion allows for nested block comments. ====Block in Haskell==== In Haskell, a block comment is delimited by {- and -} . For example: {- this is a comment on more lines -} -- and this is a comment on one line putStrLn "Wikipedia" -- this is another comment Haskell also provides a literate programming method of commenting known as "Bird Style". Lines starting with > are interpreted as code and everything else is considered a comment. One additional requirement is a blank line before and after the code block: In Bird-style you have to leave a blank before the code. > fact :: Integer -> Integer > fact 0 = 1 > fact (n+1) = (n+1) * fact n And you have to leave a blank line after the code as well. Literate programming can also be accomplished via LaTeX. Example of a definition: \usepackage{verbatim} \newenvironment{code}{\verbatim}{\endverbatim} Used as follows: % the LaTeX source file The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\ \begin{code} fact :: Integer -> Integer fact 0 = 1 fact (n+1) = (n+1) * fact n \end{code} Here more explanation using \LaTeX{} markup ====Block in Lua==== Lua supports block comments delimited by -- and For example: --A multi-line long comment ===Less common syntax=== ====APL==== APL uses ⍝ ("lamp") for a line comment. For example: ⍝ Now add the numbers: c←a+b ⍝ addition In dialects that have the ⊣ ("left") and ⊢ ("right") primitives, comments can often be inside or separate statements, in the form of ignored strings: d←2×c ⊣'where'⊢ c←a+ 'bound'⊢ b ====AppleScript==== AppleScript supports both line and block comments. For example: line comment (in later versions) (* This program displays a greeting. ) on greet(myGreeting) display dialog myGreeting & " world!" end greet -- Show the greeting greet("Hello") ==== BASIC==== Early versions of BASIC used (short for remark) for a line comment. 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 In later variations, including Quick Basic, Q Basic, Visual Basic (VB), VB.NET, VBScript, FreeBASIC and Gambas, a line comment is delimited with ' (apostrophe). An example in VB.NET: Public Class Form1 Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click ' new style line comment rem old style line comment still supported MessageBox.Show("Hello, World") ' show dialog with a greeting End Sub End Class ====Cisco IOS and IOS-XE configuration==== The exclamation point (!) may be used to mark comments in a Cisco router's configuration mode, however such comments are not saved to non-volatile memory (which contains the startup-config), nor are they displayed by the "show run" command. It is possible to insert human-readable content that is actually part of the configuration, and may be saved to the NVRAM startup-config via: The "description" command, used to add a description to the configuration of an interface or of a BGP neighbor The "name" parameter, to add a remark to a static route The "remark" command in access lists ! Paste the text below to reroute traffic manually config t int gi0/2 no shut ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2 no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1 int gi0/1 shut exit ====Fortran==== The following fixed-form Fortran code fragment shows that comment syntax is column-oriented. A letter C in the first column causes the entire line to be treated as a comment. In Fortran 77, an asterisk in column 1 also indicates a comment. C C Lines beginning with 'C' in the first (a.k.a. comment) column are comments C WRITE (6,610) 610 FORMAT(12H HELLO WORLD) END The following Fortran 90 code fragment shows a more modern line comment syntax: text following ! . ! A comment program comment_test print '(A)', 'Hello world' ! also a comment end program Free-form Fortran, also introduced with Fortran 90, only supports this latter style of comment. Although not a part of the Fortran Standard, many Fortran compilers offer an optional C-like preprocessor pass. This can be used to provide block comments: if 0 This is a block comment spanning multiple lines. endif program comment_test print '(A)', 'Hello world' ! also a comment end program ====MATLAB==== In MATLAB's programming language, the '%' character indicates a single-line comment. Multi line comments are also available via %{ and %} brackets and can be nested, e.g. % These are the derivatives for each term d = [0 -1 0]; %{ %{ (Example of a nested comment, indentation is for cosmetics (and ignored).) %} We form the sequence, following the Taylor formula. Note that we're operating on a vector. %} seq = d .* (x - c).^n ./(factorial(n)) % We add-up to get the Taylor approximation approx = sum(seq) ====Nim==== Nim delimits a line comment with # and block comments with #[ and ]# . Block comments can be nested. Nim also has documentation comments that use mixed Markdown and ReStructuredText markups. A line documentation comment uses '##' and a block documentation comment uses '##[' and ']##'. The compiler can generate HTML, LaTeX and JSON documentation from the documentation comments. Documentation comments are part of the abstract syntax tree and can be extracted using macros. Documentation of the module *ReSTructuredText* and **MarkDown** This is a comment, but it is not a documentation comment. type Kitten = object ## Documentation of type age: int ## Documentation of field proc purr(self: Kitten) = ## Documentation of function echo "Purr Purr" # This is a comment, but it is not a documentation comment. This is a comment, but it is not a documentation comment. ====OCaml==== OCaml supports nestable comments. For example: codeLine(* comment level 1(*comment level 2*)*) ====Pascal, Delphi==== In Pascal and Delphi, a block comment is delimited by { and } , and as an alternative for computers that do not support these characters, (* and *) are also supported. A line comment is delimited by \\ . In Niklaus Wirth's more modern family of languages (including Modula-2 and Oberon), comments are delimited by (* and *) . Comments can be nested. For example: (* test diagonals *) columnDifference := testColumn - column; if (row + columnDifference = testRow) or ....... ====PHP==== Comments in PHP can be either curly brace style (both line and block), or line delimited with # l. Blocks cannot be nested. Starting in PHP 8, a # only means comment if it's not immediately followed by [ . Otherwise, it delimits an attribute, which continues till the next ] . For example: /** * This class contains a sample documentation. * @author Unknown */ [Attribute] class MyAttribute { const VALUE = 'value'; // C++ style line comment private $value; # script style line comment public function __construct($value = null) { $this->value = $value; } } ===Double dash=== A relatively loose collection of languages use -- for a single line comment. Notable languages include: Ada, Eiffel, Haskell, Lua, SQL and VHDL. Block comment support varies. An example in 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; ==Security issues== In interpreted languages, depending on the operating system's capabilities and the administrator's choices, the entire source code, including the comments, may be viewable to the program's end user. This may present a security vulnerability, when comments contain secrets or when secret sections of code are merely commented out. ==See also== Comparison of programming languages (syntax)#Comments ==Notes and references== ==External links== How to Write Comments by Denis Krukovsky Source Code Documentation as a Live User Manual by PTLogica How to Write Comments for the Javadoc Tool

Text derived from https://en.wikipedia.org/w/index.php?oldid=1373605790 under CC BY-SA 4.0; modifications have been made.