Content deleted Content added
Stevebroshar (talk | contribs) →Nim: Use line/block consistently |
Velocifyer (talk | contribs) |
||
| (21 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
▲The [[comparison of programming languages (syntax)#Comments|syntax of comments]] varies considerably by [[programming language]]. But generally, the flexibility supported by comments allows for a wide degree of style variability. To promote uniformity, conventions for their style 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
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">
▲Most modern 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" />
/*
* 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 564 ⟶ 574:
====APL====
[[APL (programming language)|APL]] uses <code>⍝</code> ("lamp") for a line comment. For example:
<syntaxhighlight lang="apl">
Line 580 ⟶ 590:
<syntaxhighlight lang="AppleScript">
# line comment (in later versions)
(*
This program displays a greeting.
Line 601 ⟶ 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 a pop-up window with a greeting
End Sub
End Class
Line 636 ⟶ 645:
====Fortran====
The following fixed-form [[Fortran
<syntaxhighlight lang="fortranfixed">
Line 651 ⟶ 660:
<syntaxhighlight lang="Fortran">
! A comment
program comment_test
print '(A)', 'Hello world' ! also a comment
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="Fortran">
#if 0
multiple lines.
#endif
program comment_test
print '(A)', 'Hello world' ! also a comment
Line 699 ⟶ 722:
====OCaml====
[[OCaml]] supports nestable comments. For
<syntaxhighlight lang="ocaml">
codeLine(* comment level 1(*comment level 2*)*)
Line 706 ⟶ 729:
====Pascal, Delphi====
▲As an alternative, for computers that do not support these characters, '(* ... *)' are allowed.<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 '(* ... *)'.<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. // can be included in a {} and {} can be included in a (**). For example:
<syntaxhighlight lang="pascal">
Line 717 ⟶ 739:
====PHP====
Comments in [[PHP]] can be either
<syntaxhighlight lang="php">
/**
* This class contains a sample documentation.
▲ *
* @author Unknown
*/
Line 730 ⟶ 749:
class MyAttribute {
const VALUE = 'value';
//
private $value;
#
public function __construct($value = null) {
$this->value = $value;
}
▲ This is a multiline comment.
}
</syntaxhighlight>
| |||