Content deleted Content added
Stevebroshar (talk | contribs) →Examples: Move powershell to scripting section |
Velocifyer (talk | contribs) |
||
| (35 intermediate revisions by 10 users not shown) | |||
Line 4:
[[File:CodeCmmt002.svg|thumb|right|300px|[[Java (programming language)|Java]] source code with block comments in <span style="color:#f00;">red</span>, line comments in <span style="color:#0e850e;">green</span> and program code in <span style="color:#00f;"> blue</span>.]]
In [[computer programming]], a '''comment''' is text embedded in [[source code]] that a translator ([[compiler]] or [[interpreter (computing)|interpreter]]) ignores. Generally, a comment is an [[annotation]] intended to make the code easier for a [[programmer]] to understand {{endash}} often explaining an aspect that is not readily apparent in the program (non-comment) code.<ref name="PennyGrubb000">{{cite book | last = Penny Grubb | first = Armstrong Takang | title = Software Maintenance: Concepts and Practice | publisher = World Scientific | year = 2003 | isbn = 978-981-238-426-3 | pages = 7, plese start120–121}}</ref> For this article, ''comment'' refers to the same concept in a [[programming
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 practice]]s are disputed and contradictory.<ref name="Dietrich000">{{cite book
| last = W. R.
| first = Dietrich
Line 28 ⟶ 26:
Support for code comments is defined by each programming language. The features differ by language, but there are several common attributes that apply throughout.
Most languages support multi-line
| title = MATLAB Guide
| first = Desmond
Line 50 ⟶ 46:
| access-date = 2007-07-24
| date = 2000-03-04
}}</ref> A '''line comment''' ends at the end of the text line. In modern languages, a line comment starts with a delimiter but some older languages designate a column at which subsequent text is considered comment.<ref name="javadude000" /> Many languages support both block and line comments {{endash}} using different delimiters for each. For example, [[C (programming language)|C]], [[C++]] and their many derivatives support block comments delimited by <code>/*</code> and <code>*/</code> and line comments delimited by <code>//</code>. Other languages support only one type of comment.<ref name="javadude000" />
Comments can also be classified as either prologue or inline based on their position and content relative to program code. A '''prologue comment''' is a comment (or group of related comments) located near the top of an associated programming topic, such as before a symbol declaration or at the top of a file. An '''inline comment''' is a comment that is located on the same line as and to the right of program code to which is refers.<ref name="JBDixit000">{{cite book | last = Dixit | first = J.B. | title = Computer Fundamentals and Programming in C | publisher = Laxmi Publications | year = 2003 | isbn = 978-81-7008-882-0 }}</ref> Both prologue and inline comments can be represented as either line or block comments. For example:
<syntaxhighlight lang="c">
/*
* prologue block comment; if is about foo()
*/
bool foo() {
return true; /* inline block comment; if is about this return */
}
//
// prologue line comment; if is about bar()
//
bool bar() {
return false; // inline line comment; if is about this return
}
</syntaxhighlight>
==Examples of use==
Line 116 ⟶ 126:
Comments can store [[metadata]] about the code. Common metadata includes the name of the original author and subsequent maintainers, dates when first written and modified, link to development and user documentation, and legal information such as [[copyright]] and [[software license]].
Some [[programming tools]] write metadata into the code as comments.<ref>See e.g., {{cite book |last=Wynne-Powell |first=Rod |year=2008 |title=Mac OS X for Photographers: Optimized Image Workflow for the Mac User |page=243 |publisher=Focal Press |___location=Oxford |isbn=978-0-240-52027-8 |url=https://archive.org/details/macosxforphotogr0000wynn}}</ref> For example, a [[version control]] tool might write metadata such as author, date and version number into each file when it's
=== Integrate with development tools ===
Line 135 ⟶ 145:
| publisher=Cambridge University Press
| isbn=978-1-397-80521-8
}}</ref> Examples include [[Javadoc]],
=== Visualization ===
Line 183 ⟶ 193:
=== Extend language syntax ===
Occasionally, code that is formatted as a comment is overloaded to convey additional information to the translator, such as
Other examples include interpreter [[Directive (programming)|directives]]:
Line 282 ⟶ 292:
<syntaxhighlight lang="c">
/***************************
* *
* This is the comment body. *
* *
</syntaxhighlight>
Line 323 ⟶ 333:
==Tags==
Programmers often use one of select words {{endash}} also
Commonly used tags include:
Line 344 ⟶ 354:
===Curly brace languages===
Many of the [[curly brace language]]s such as C, C++ and their many derivatives delimit a line comment with {{code|//}} and a block comment with {{code|/*}} and {{code|*/}}. Originally, C lacked the line comment, but it was added in [[C99]]. Notable languages include: C, C++, [[C# (programming language)|C#]], [[D (programming language)|D]], [[Java (programming language)|Java]], [[
<syntaxhighlight lang="c">
Line 357 ⟶ 367:
</syntaxhighlight>
Some languages, including D and Swift, allow blocks to be nested while other do not, including C and C++.
An example of nested blocks in <syntaxhighlight lang="d">
// line comment
/*
block comment
*/
/+ start of outer block
/+ inner block +/
end of outer block +/
</syntaxhighlight>
An example of nested blocks in Swift:
<syntaxhighlight lang="swift">
Line 367 ⟶ 391:
===Scripting===
A pattern in many [[scripting language]]s is to delimit a line comment with <code>#</code>.
An example in R:
Line 374 ⟶ 398:
# This is a comment
print("This is not a comment") # This is another comment
</syntaxhighlight>
====Block in Ruby====
A block comment is delimited by <code>=begin</code> and <code>=end</code> that start a line. For example:
<syntaxhighlight lang="ruby">
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"
</syntaxhighlight>
Line 389 ⟶ 427:
<syntaxhighlight lang="perl">
=item Pod::List-E<gt>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 {
...
Line 402 ⟶ 436:
</syntaxhighlight>
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".<ref name=perl6>
{{cite web
| title = Perl 6 Documentation – Syntax (Comments)
Line 413 ⟶ 446:
#`{{ "commenting out" this version
toggle-case(Str:D $s)
Toggles the case of each character in a string:
my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");
}}
sub toggle-case(Str:D $s) #`( this version of parens is used now ){
...
Line 451 ⟶ 480:
"""Method docstring"""
</syntaxhighlight>
===
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 <code><!--</code> and <code>--></code> and provide no line comment support. An example in XML:
<syntaxhighlight lang="xml">
<!-- select the context here -->
<param name="context" value="public" />
</syntaxhighlight>
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.
===Double dash===
A relatively loose collection of languages use <code>--</code> for a single line comment. Notable languages include: [[Ada (programming language)|Ada]], [[Eiffel (programming language)|Eiffel]], [[Haskell (programming language)|Haskell]], [[Lua (programming language)|Lua]], [[SQL]] and [[VHDL]]. Block comment support varies. An example in Ada:
<syntaxhighlight lang="ada">
</syntaxhighlight>
====Block in Haskell====
In Haskell, a block comment is delimited by <code>{-</code> and <code>-}</code>. For example:
<syntaxhighlight lang="Haskell">
{- this is a comment
on more lines -}
-- and this is a comment on one line
putStrLn "Wikipedia" -- this is another comment
</syntaxhighlight>
Haskell also provides a [[literate programming]] method of commenting known as "Bird Style".<ref>{{cite web |url=http://www.haskell.org/haskellwiki/Literate_programming#Bird_Style |title=Literate programming |website=haskell.org}}</ref> Lines starting with <code>></code> are interpreted as code and everything else is considered a comment. One additional requirement is a blank line before and after the code block:
<syntaxhighlight lang="lHaskell">
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.
</syntaxhighlight>
Literate programming can also be accomplished via [[LaTeX]]. Example of a definition:
<syntaxhighlight lang="lHaskell">
\usepackage{verbatim}
\newenvironment{code}{\verbatim}{\endverbatim}
</syntaxhighlight>
Used as follows:
<syntaxhighlight lang="lhaskell">
% 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
</syntaxhighlight>
====Block in Lua====
Lua supports block comments delimited by <code>--[[</code> and <code>]]</code><ref>{{Cite web|url=http://www.lua.org/pil/1.3.html|title=Programming in Lua 1.3|website=www.Lua.org|access-date=2017-11-08}}</ref> For example:
<syntaxhighlight lang="lua">
--[[A multi-line
long comment
]]
</syntaxhighlight>
==== Block in SQL ====
In some variants of SQL, the curly brace language block comment (<code>/**/</code>) is supported. Variants include: [[Transact-SQL]], [[MySQL]], [[SQLite]], [[PostgreSQL]], and [[Oracle Database|Oracle]].<ref name="MSSQL">{{cite book
| title = Microsoft SQL Server 7
| first = Ronald R.
| last = Talmage
| publisher = Prima Publishing
| year = 1999
| isbn = 978-0-7615-1389-6
| url = https://archive.org/details/microsoftsqlserv00talm
}}</ref><ref name="MySQL">{{cite web | url=https://dev.mysql.com/doc/refman/8.0/en/comments.html | title=MySQL 8.0 Reference Manual | publisher=Oracle Corporation | access-date=January 2, 2020}}</ref><ref name="SQLite">{{cite web | url=https://www.sqlite.org/lang_comment.html | title=SQL As Understood By SQLite | publisher=SQLite Consortium | access-date=January 2, 2020}}</ref><ref name="PostgreSQL">{{cite web | url=https://www.postgresql.org/docs/10/sql-syntax-lexical.html#SQL-SYNTAX-COMMENTS | title=PostgreSQL 10.11 Documentation | publisher=The PostgreSQL Global Development Group | access-date=January 2, 2020}}</ref><ref name="Oracle">{{cite web | url=https://docs.oracle.com/cd/B13789_01/server.101/b10759/sql_elements006.htm | title=Oracle® Database SQL Reference | publisher=Oracle Corporation | access-date=January 2, 2020}}</ref>
MySQL also supports a line comment delimited by <code>#</code>.
===Less common syntax===
====APL====
[[APL (programming language)|APL]] uses <code>⍝</code> ("lamp") for a line comment. For example:
<syntaxhighlight lang="apl">
Line 484 ⟶ 590:
<syntaxhighlight lang="AppleScript">
# line comment (in later versions)
(*
This program displays a greeting.
Line 505 ⟶ 612:
</syntaxhighlight>
In later variations, including [[Quick Basic]], [[Q Basic]], [[Visual Basic]] (VB), [[Visual Basic .NET|VB.NET]], [[
<syntaxhighlight lang="vbnet">
Public Class Form1
Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
'
MessageBox.Show("Hello, World") ' show dialog with a greeting
End Sub
End Class
Line 539 ⟶ 644:
</syntaxhighlight>
====
The following fixed-form [[Fortran]] code fragment shows that comment syntax is column-oriented. A letter <code>C</code> 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.
<syntaxhighlight lang="fortranfixed">
C
C Lines
C
WRITE (6,610)
Line 579 ⟶ 656:
</syntaxhighlight>
The following [[Fortran|Fortran 90]] code fragment shows a more modern line comment syntax; text following <code>!</code>.
<syntaxhighlight lang="Fortran">
! A comment
program comment_test
print '(A)', 'Hello world' !
end program
</syntaxhighlight>
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:
<syntaxhighlight lang="
#if 0
This is a block comment spanning
multiple lines.
#endif
program comment_test
print '(A)', 'Hello world' ! also a comment
end program
</syntaxhighlight>
====MATLAB====
Line 685 ⟶ 700:
====Nim====
[[Nim (programming language)|Nim]]
Nim also has documentation comments that use mixed [[Markdown]] and [[ReStructuredText]] markups.
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.<ref>[https://nim-lang.github.io/Nim/macros.html#extractDocCommentsAndRunnables%2CNimNode macros.extractDocCommentsAndRunnables]</ref>
Line 709 ⟶ 722:
====OCaml====
[[OCaml]] supports nestable comments. For
<syntaxhighlight lang="ocaml">
codeLine(* comment level 1(*comment level 2*)*)
Line 716 ⟶ 729:
====Pascal, Delphi====
In [[Pascal (programming language)|Pascal]] and [[Delphi (software)|Delphi]], a block comment is delimited by <code>{</code> and <code>}</code>, and as an alternative for computers that do not support these characters, <code>(*</code> and <code>*)</code> are also supported. A line comment is delimited by <code>\\</code>.<ref>{{cite book|author=Kathleen Jensen, Niklaus Wirth|year=1985|title=Pascal User Manual and Report|publisher=Springer-Verlag|isbn=0-387-96048-1}}</ref> In [[Niklaus Wirth]]'s more modern family of languages (including [[Modula-2]] and [[Oberon (programming language)|Oberon]]), comments are delimited by <code>(*</code> and <code>*)</code>.<ref>{{cite book|author=Niklaus Wirth|year=1983|title=Programming in Modula-2|publisher=Springer-Verlag|isbn=0-387-15078-1}}</ref><ref>*{{cite book|author=Martin Reiser, Niklaus Wirth|year=1992|title=Programming in Oberon|publisher=Addison-Wesley|isbn=0-201-56543-9}}</ref> Comments can be nested. For example:
<syntaxhighlight lang="pascal">
Line 727 ⟶ 739:
====PHP====
Comments in [[PHP]] can be either
<syntaxhighlight lang="php">
/**
* This class contains a sample documentation.
* @author Unknown
*/
Line 740 ⟶ 749:
class MyAttribute {
const VALUE = 'value';
//
private $value;
#
public function __construct($value = null) {
$this->value = $value;
}
}
</syntaxhighlight>
==Security issues==
Line 821 ⟶ 769:
==See also==
* [[Comparison of programming languages (syntax)#Comments]]
==Notes and references==
| |||