Comment (computer programming)
Encyclopedia
In computer programming
Computer programming
Computer programming is the process of designing, writing, testing, debugging, and maintaining the source code of computer programs. This source code is written in one or more programming languages. The purpose of programming is to create a program that performs specific operations or exhibits a...

, a comment is a programming language
Programming language
A programming language is an artificial language designed to communicate instructions to a machine, particularly a computer. Programming languages can be used to create programs that control the behavior of a machine and/or to express algorithms precisely....

 construct used to embed programmer-readable annotation
Annotation
An annotation is a note that is made while reading any form of text. This may be as simple as underlining or highlighting passages.Annotated bibliographies give descriptions about how each source is useful to an author in constructing a paper or argument...

s in the source code
Source code
In computer science, source code is text written using the format and syntax of the programming language that it is being written in. Such a language is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source...

 of a computer program
Computer program
A computer program is a sequence of instructions written to perform a specified task with a computer. A computer requires programs to function, typically executing the program's instructions in a central processor. The program has an executable form that the computer can use directly to execute...

. Those annotations are potentially significant to programmers but typically ignorable to compiler
Compiler
A compiler is a computer program that transforms source code written in a programming language into another computer language...

s and interpreter
Interpreter (computing)
In computer science, an interpreter normally means a computer program that executes, i.e. performs, instructions written in a programming language...

s. Comments are usually added with the purpose of making the source code easier to understand. The syntax and rules for comments vary and are usually defined in a programming language specification
Programming language specification
In computing, a programming language specification is an artifact that defines a programming language so that users and implementors can agree on what programs in that language mean....

 (see the syntax of comments in various programming languages).

Comments have a wide range of potential uses: from augmenting program code with basic descriptions, to generating external documentation
Documentation generator
A documentation generator is a programming tool that generates documentation intended for programmers or end users , or both, from a set of specially commented source code files, and in some cases, binary files....

. Comments are also used for integration with source code management systems and other kinds of external programming tool
Programming tool
A programming tool or software development tool is a program or application that software developers use to create, debug, maintain, or otherwise support other programs and applications...

s.

The flexibility provided by comments often allows for a wide degree of variability and potentially non-useful information inside source code. To address this, many technical commentators and software analysts subscribe to any of several "philosophies" and guidelines regarding the proper use of comments.

Overview

Comments are generally formatted as block comments (also called prologue comments or stream comments) or line comments (also called inline comments).

Block comments delimit a region of source code in which the region is allowed to span multiple lines. This region is specified with a start delimiter and an end delimiter. Some programming languages (such as MATLAB
MATLAB
MATLAB is a numerical computing environment and fourth-generation programming language. Developed by MathWorks, MATLAB allows matrix manipulations, plotting of functions and data, implementation of algorithms, creation of user interfaces, and interfacing with programs written in other languages,...

) allow block comments to be recursively nested inside one another, but others (such as Java
Java (programming language)
Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...

) do not.

Line comments either start with a comment delimiter and continue until the end of the line, or in some cases, start at a specific column (character line offset) in the source code, and continue until the end of the line.

Some programming languages employ both block and line comments with different comment delimiters. For example, C++
C++
C++ is a statically typed, free-form, multi-paradigm, compiled, general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level and low-level language features. It was developed by Bjarne Stroustrup starting in 1979 at Bell...

 has block comments delimited by /* and */ that can span multiple lines and line comments delimited by //. Other languages support only one type of comment. For example, Ada
Ada (programming language)
Ada is a structured, statically typed, imperative, wide-spectrum, and object-oriented high-level computer programming language, extended from Pascal and other languages...

 comments are line comments: they start with -- and continue to the end of the line.

Uses

How best to make use of comments is subject to dispute; different commentators have offered varied and sometimes opposing viewpoints.
There are many different ways of writing comments and many commentators who offer sometimes conflicting advice.

Planning / Reviewing

Comments can be used as a form of pseudocode
Pseudocode
In computer science and numerical computation, pseudocode is a compact and informal high-level description of the operating principle of a computer program or other algorithm. It uses the structural conventions of a programming language, but is intended for human reading rather than machine reading...

 to outline intention prior to writing the actual code. In this case it should explain the logic behind the code rather than the code itself.

/* 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]);
}


If this type of comment is left in, it simplifies the review process by allowing a direct comparison of the code with the intended results. A common logical fallacy is that code that is easy to understand does what it's supposed to do.

Code description

Comments can be used to summarize code or to explain the programmer's intent. According to this school of thought, restating the code in plain English is considered superfluous; the need to re-explain code may be a sign that it is too complex and should be rewritten.
"Don't document bad code – rewrite it."

"Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do."


Comments may also be used to explain why a block of code does not seem to fit conventions or best practices. This is especially true of projects involving very little development time, or in bug fixing. For example:
' 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")

Algorithmic description

Sometimes source code contains a novel or noteworthy solution to a specific problem. In such cases, comments may contain an explanation of the methodology. Such explanations may include diagrams and formal mathematical proofs. This may constitute explanation of the code, rather than a clarification of its intent; but others tasked with maintaining the code base may find such explanation crucial. This might especially be true in the case of highly-specialized problem domains; or rarely-used optimizations, constructs or function-calls.

For example, a programmer may add a comment to explain why an insertion sort
Insertion sort
Insertion sort is a simple sorting algorithm: a comparison sort in which the sorted array is built one entry at a time. It is much less efficient on large lists than more advanced algorithms such as quicksort, heapsort, or merge sort...

 was chosen instead of a quicksort, as the former is, in theory, slower than the latter. This could be written as follows:

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);

Resource inclusion

Logo
Logo
A logo is a graphic mark or emblem commonly used by commercial enterprises, organizations and even individuals to aid and promote instant public recognition...

s, diagrams, and flowchart
Flowchart
A flowchart is a type of diagram that represents an algorithm or process, showing the steps as boxes of various kinds, and their order by connecting these with arrows. This diagrammatic representation can give a step-by-step solution to a given problem. Process operations are represented in these...

s consisting of ASCII art
ASCII art
ASCII art is a graphic design technique that uses computers for presentation and consists of pictures pieced together from the 95 printable characters defined by the ASCII Standard from 1963 and ASCII compliant character sets with proprietary extended characters...

 constructions can be inserted into source code formatted as a comment. Further, copyright
Copyright
Copyright is a legal concept, enacted by most governments, giving the creator of an original work exclusive rights to it, usually for a limited time...

 notices can be embedded within source code as comments. Binary data may also be encoded in comments through a process known as binary-to-text encoding, although such practice is uncommon and typically relegated to external resource files.

The following code fragment is a simple ASCII diagram depicting the process flow for a system administration script contained in a Windows Script File
Windows Script File
A Windows Script File is a file type used by the Microsoft Windows Script Host. It allows mixing the scripting languages JScript and VBScript within a single file, or other scripting languages such as Perl, Object REXX, Python, or Kixtart if installed by the user...

 running under Windows Script Host
Windows Script Host
The Microsoft Windows Script Host is an automation technology for Microsoft Windows operating systems that provides scripting capabilities comparable to batch files, but with a greater range of supported features...

. Although a section marking the code appears as a comment, the diagram itself actually appears in an XML
XML
Extensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....

 CDATA
CDATA
The term CDATA, meaning character data, is used for distinct, but related, purposes in the markup languages SGML and XML. The term indicates that a certain portion of the document is general character data, rather than non-character data or character data with a more specific, limited...

 section, which is technically considered distinct from comments, but can serve similar purposes.




HostApp (Main_process)
|
V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
|
|
V
mru.ini (mru_history)
]]>



Although this identical diagram could easily have been included as a comment, the example illustrates one instance where a programmer may opt not to use comments as a way of including resources in source code.


Debugging

A common developer practice is to comment out a code snippet
Snippet (programming)
Snippet is a programming term for a small region of re-usable source code, machine code or text. Ordinarily, these are formally-defined operative units to incorporate into larger programming modules...

, meaning to add comment syntax causing that block of code to become a comment, so that it will not be executed in the final program. This may be done to exclude certain pieces of code from the final program, or (more commonly) it can be used to find the source of an error. By systematically commenting out and running parts of the program, the source of an error can be determined, allowing it to be corrected. An example of commenting out code for exclusion purposes is below:

For example, one might write:

if (opt.equals ("e"))
opt_enabled = true;
/*
if (opt.equals ("d"))
opt_debug = true;
// */
//*
if (opt.equals ("v"))
opt_verbose = true;
// */

The above code fragment suggests that the programmer opted to disable the debugging option for some reason. This specific comment style is more suitable for debugging. A single slash character in front of the opening delimiter is the switch on en/disabling the block comments.

Automatic documentation generation

Programming tool
Programming tool
A programming tool or software development tool is a program or application that software developers use to create, debug, maintain, or otherwise support other programs and applications...

s sometimes store documentation and metadata
Metadata
The term metadata is an ambiguous term which is used for two fundamentally different concepts . Although the expression "data about data" is often used, it does not apply to both in the same way. Structural metadata, the design and specification of data structures, cannot be about data, because at...

 in comments. These may include insert positions for automatic header file inclusion, commands to set the file's syntax highlighting
Syntax highlighting
Syntax highlighting is a feature of some text editors that display text—especially source code—in different colors and fonts according to the category of terms. This feature eases writing in a structured language such as a programming language or a markup language as both structures and...

 mode, or the file's revision number
Revision control
Revision control, also known as version control and source control , is the management of changes to documents, programs, and other information stored as computer files. It is most commonly used in software development, where a team of people may change the same files...

. These functional control comments are also commonly referred to as annotation
Annotation
An annotation is a note that is made while reading any form of text. This may be as simple as underlining or highlighting passages.Annotated bibliographies give descriptions about how each source is useful to an author in constructing a paper or argument...

s. Keeping documentation within source code comments is considered as one way to simplify the documentation process, as well as increase the chances that the documentation will be kept up to date with changes in the code.

Examples of documentation generators include the programs Javadoc
Javadoc
Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, such as Netbeans and Eclipse automatically generate...

 for use with Java
Java (programming language)
Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...

, Ddoc
Ddoc
Ddoc is the embedded documentation generator for the D programming language designed by Walter Bright. Its emphasis is on being able to write documentation in code comments in a natural style, minimizing the need for embedded markup and thus improving the legibility of the code comments...

 for D
D (programming language)
The D programming language is an object-oriented, imperative, multi-paradigm, system programming language created by Walter Bright of Digital Mars. It originated as a re-engineering of C++, but even though it is mainly influenced by that language, it is not a variant of C++...

, Doxygen
Doxygen
Doxygen is a documentation generator for multiple programming languages.Doxygen is a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date...

 for C
C (programming language)
C is a general-purpose computer programming language developed between 1969 and 1973 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system....

, C++
C++
C++ is a statically typed, free-form, multi-paradigm, compiled, general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level and low-level language features. It was developed by Bjarne Stroustrup starting in 1979 at Bell...

, Java, IDL
Interface description language
An interface description language , or IDL for short, is a specification language used to describe a software component's interface...

, and PHPDoc
PHPDoc
PHPDoc is an adaptation of Javadoc for the PHP programming language. It is a formal standard for commenting PHP code. It allows external document generators like phpDocumentor to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState...

 for PHP
PHP
PHP is a general-purpose server-side scripting language originally designed for web development to produce dynamic web pages. For this purpose, PHP code is embedded into the HTML source document and interpreted by a web server with a PHP processor module, which generates the web page document...

. [interface description language|Accountants]

C# and Visual Basic
Visual Basic
Visual Basic is the third-generation event-driven programming language and integrated development environment from Microsoft for its COM programming model...

 implement a similar feature called "XML Comments" which are read by IntelliSense
IntelliSense
IntelliSense is Microsoft's implementation of autocompletion, best known for its use in the Microsoft Visual Studio integrated development environment...

 from the compiled .NET
.NET Framework
The .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...

 assembly.

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.

Need for comments

Technical commentators have documented varying viewpoints on whether and when comments are appropriate in source code.
Some commentators assert that source code should be written with few comments, on the basis that the source code should be self-explanatory. Others suggest code should be extensively commented (it is not uncommon for over 50% of the non-whitespace
Whitespace (computer science)
In computer science, whitespace is any single character or series of characters that represents horizontal or vertical space in typography. When rendered, a whitespace character does not correspond to a visual mark, but typically does occupy an area on a page...

 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.

Level of detail

Depending on the intended audience of the code and other considerations, the level of detail and description may vary considerably.

For example, the following Java comment would be suitable in an introductory text designed to teach beginning 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.

Offensive comments

Sometimes comments in source code are used as a way to relieve stress or to speak unfavorably about development tools, competitors, employers, working conditions, or even the quality of the code itself. Some commentators deem this highly inappropriate and recommend against including potentially offensive remarks in comments, especially if there is any possibility that the source code may later be viewed by anyone besides the original developer responsible for it. The occurrence of this phenomenon can be easily seen from online resources that track profanity
Profanity
Profanity is a show of disrespect, or a desecration or debasement of someone or something. Profanity can take the form of words, expressions, gestures, or other social behaviors that are socially constructed or interpreted as insulting, rude, vulgar, obscene, desecrating, or other forms.The...

 in source code.

Comments in web templates

Web development presents a special security challenge related to comments, because it is not uncommon for HTML comments to be viewable in plain text by any user of the application. Sections of code that are "commented out" in HTML templates may therefore present a security vulnerability
Vulnerability (computing)
In computer security, a vulnerability is a weakness which allows an attacker to reduce a system's information assurance.Vulnerability is the intersection of three elements: a system susceptibility or flaw, attacker access to the flaw, and attacker capability to exploit the flaw...

.

Styles

There are many stylistic alternatives available when considering how comments should appear in source code. For larger projects involving a team of developers, comment styles are either agreed upon before a project starts, or evolve as a matter of convention or need as a project grows. Usually programmers prefer styles that are consistent, non-obstructive, easy to modify, and difficult to break.

The following code fragments in C demonstrate just a tiny example of how comments can vary stylistically, while still conveying the same basic information:

/*
This is the comment body.
Variation One.



/***************************\
  • *
  • This is the comment body. *
  • Variation Two. *
  • *

\***************************/


Factors such as personal preference, flexibility of programming tools, and other considerations tend to influence the stylistic variants used in source code. For example, Variation Two might be disfavored among programmers who do not have source code editor
Source code editor
A source code editor is a text editor program designed specifically for editing source code of computer programs by programmers. It may be a standalone application or it may be built into an integrated development environment ....

s that can automate the alignment and visual appearance of text in comments.

Software consultant and technology commentator Allen Holub is one expert who 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.
*/

End-of-line

In this form, all the text from the ASCII characters // to the end of the line is ignored.

// begin: Variation Three.
// -------------------------
// This is the comment body.
// -------------------------


Different styles can be chosen for different areas of code, from individual lines to paragraphs, routines, files, and programs. If the syntax supports both line comments and block comments, one method is to use line comments only for minor comments (declarations, blocks and edits) and to use block comments to describe higher-level abstractions (functions, classes, files and modules).

Sometimes projects try to enforce rules like "one comment every ten lines". These kinds of rules can be counterproductive when too rigorous, but may provide a useful standard of measurement and consistency if the project participants deem it necessary.

Tags

Certain tags
Tag (metadata)
In online computer systems terminology, a tag is a non-hierarchical keyword or term assigned to a piece of information . This kind of metadata helps describe an item and allows it to be found again by browsing or searching...

 are used in comments to assist in indexing common issues. Such tags are commonly syntax-highlighted
Syntax highlighting
Syntax highlighting is a feature of some text editors that display text—especially source code—in different colors and fonts according to the category of terms. This feature eases writing in a structured language such as a programming language or a markup language as both structures and...

 within text editor
Text editor
A text editor is a type of program used for editing plain text files.Text editors are often provided with operating systems or software development packages, and can be used to change configuration files and programming language source code....

s and can be searched with common programming tools, such as the Unix
Unix
Unix is a multitasking, multi-user computer operating system originally developed in 1969 by a group of AT&T employees at Bell Labs, including Ken Thompson, Dennis Ritchie, Brian Kernighan, Douglas McIlroy, and Joe Ossanna...

 grep
Grep
grep is a command-line text-search utility originally written for Unix. The name comes from the ed command g/re/p...

 utility. Examples of tag conventions include:
  • FIXME to mark potential problematic code that requires special attention and/or review.
  • NOTE to document inner workings of code and indicate potential pitfalls.
  • TODO to indicate planned enhancements.
  • XXX to warn other programmers of problematic or misguiding code.


There is a risk that tags accumulate over time; it is advisable to include the date and the tag owner in the tag comment to ease tracking.

Comparison

Typographic conventions to specify comments vary widely. Further, individual programming languages sometimes provide unique variants. For a detailed review, please consult the programming language comparison article.

BASIC classic

This BASIC
BASIC
BASIC is a family of general-purpose, high-level programming languages whose design philosophy emphasizes ease of use - the name is an acronym from Beginner's All-purpose Symbolic Instruction Code....

 code fragment is a completely functioning program in which the comments describe what the program does for the benefit of novice programmers.

10 REM This BASIC program shows the use of the PRINT and GOTO statements.
15 REM It fills the screen with the word "WIKIPEDIA"
20 PRINT "WIKIPEDIA"
30 GOTO 20

When run, this program repeatedly prints the word "WIKIPEDIA" (without quotes) in an infinite loop
Infinite loop
An infinite loop is a sequence of instructions in a computer program which loops endlessly, either due to the loop having no terminating condition, having one that can never be met, or one that causes the loop to start over...

.

C

This C
C (programming language)
C is a general-purpose computer programming language developed between 1969 and 1973 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system....

 code fragment demonstrates the use of a prologue comment or "block comment" to describe the purpose of a conditional statement
Conditional statement
In computer science, conditional statements, conditional expressions and conditional constructs are features of a programming language which perform different computations or actions depending on whether a programmer-specified boolean condition evaluates to true or false...

. The comment explains key terms and concepts, and includes a short signature by the programmer who authored the code.

/*
* 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;

This excerpt is from the fork.c file from the Linux kernel
Linux kernel
The Linux kernel is an operating system kernel used by the Linux family of Unix-like operating systems. It is one of the most prominent examples of free and open source software....

 source.

ColdFusion

ColdFusion
ColdFusion
In computing, ColdFusion is the name of a commercial rapid application development platform invented by Jeremy and JJ Allaire in 1995. ColdFusion was originally designed to make it easier to connect simple HTML pages to a database, by version 2 it had...

 uses comments similar to HTML/XML, but instead of two dashes, it uses three. These comments are caught by the ColdFusion engine and not printed to the browser.




Hello World



Fortran IV

This Fortran IV code fragment demonstrates how comments are used in that language, with the comments themselves describing the basic formatting rules.

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

This Fortran
Fortran
Fortran is a general-purpose, procedural, imperative programming language that is especially suited to numeric computation and scientific computing...

 code fragment demonstrates how comments are used in that language, with the comments themselves describing the basic formatting rules.

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* All characters after an exclamation mark are considered as comments *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

PRINT "WIKIPEDIA" ! Fortran 90 introduced the option for inline comments.
END

Java

This Java
Java (programming language)
Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...

 code fragment shows a block comment used to describe the setToolTipText method. The formatting is consistent with Sun Microsystems
Sun Microsystems
Sun Microsystems, Inc. was a company that sold :computers, computer components, :computer software, and :information technology services. Sun was founded on February 24, 1982...

 Javadoc
Javadoc
Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, such as Netbeans and Eclipse automatically generate...

 standards. The comment is designed to be read by the Javadoc processor.

/**
* 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) {

Objective Caml

OCaml uses nestable comments, which is useful when commenting a code block.

codeLine(* comment level 1(*comment level 2*)*)

Perl

Line comments in Perl
Perl
Perl is a high-level, general-purpose, interpreted, dynamic programming language. Perl was originally developed by Larry Wall in 1987 as a general-purpose Unix scripting language to make report processing easier. Since then, it has undergone many changes and revisions and become widely popular...

, and many other scripting languages, begin with a hash (#) symbol. A comment at the beginning, called the shebang
Shebang (Unix)
In computing, a shebang is the character sequence consisting of the characters number sign and exclamation point , when it occurs as the first two characters on the first line of a text file...

, tells the system what interpreter to use.
  1. !/usr/bin/perl

my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s . "\n"; # Add a newline character after printing for shells that do not do so automatically.


Instead of a regular block commenting construct, Perl uses Plain Old Documentation
Plain Old Documentation
Plain Old Documentation, abbreviated pod, is a lightweight markup language used to document the Perl programming language.-Design:pod is designed to be a simple, clean language with just enough syntax to be useful. It purposefully does not include mechanisms for fonts, images, colors or tables...

, a markup language for literate programming
Literate programming
Literate programming is an approach to programming introduced by Donald Knuth as an alternative to the structured programming paradigm of the 1970s....

, for instance:
item Pod::List-Enew

Create a new list object. Properties may be specified through a hash
reference like this:

my $list = Pod::List->new({ -start => $., -indent => 4 });

See the individual methods/properties for details.
cut

sub new {
my $this = shift;
my $class = ref($this) || $this;
my %params = @_;
my $self = {%params};
bless $self, $class;
$self->initialize;
return $self;
}

PHP

Comments in PHP
PHP
PHP is a general-purpose server-side scripting language originally designed for web development to produce dynamic web pages. For this purpose, PHP code is embedded into the HTML source document and interpreted by a web server with a PHP processor module, which generates the web page document...

 can be either in C++ style (both inline and block), or use shebangs. PHPDoc
PHPDoc
PHPDoc is an adaptation of Javadoc for the PHP programming language. It is a formal standard for commenting PHP code. It allows external document generators like phpDocumentor to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState...

 is a style adapted from Javadoc and is a common standard for documenting PHP code.

Python

Comments in Python
Python (programming language)
Python is a general-purpose, high-level programming language whose design philosophy emphasizes code readability. Python claims to "[combine] remarkable power with very clear syntax", and its standard library is large and comprehensive...

 use the hash character. Python programs start with #!
Shebang (Unix)
In computing, a shebang is the character sequence consisting of the characters number sign and exclamation point , when it occurs as the first two characters on the first line of a text file...

 to tell the operating system which interpreter to use.
  1. !/usr/bin/env python

  1. this program prints "Hello World" to the screen and then quits.

print "Hello World!"


Python also supports docstring
Docstring
In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source...

s a special sort of comment usually enclosed in triple-quotes ().


def foo(x, y):
Frobnicate the bar and baz
together with one another
return frob(frob(x), frob(y))

Ruby

Comments in Ruby
Ruby (programming language)
Ruby is a dynamic, reflective, general-purpose object-oriented programming language that combines syntax inspired by Perl with Smalltalk-like features. Ruby originated in Japan during the mid-1990s and was first developed and designed by Yukihiro "Matz" Matsumoto...

.

Single line commenting: (line starts with hash "#")

puts "This is not a comment"
  1. this is commented


puts "This is not a comment"


Multi-line commenting: (comments goes between keywords "begin" and "end")

puts "This is not a comment"

SQL

Comments in SQL are in single-line-only form, when using two dashes:

-- This is a single line comment
-- followed by a second line
SELECT COUNT(*)
FROM Authors
WHERE Authors.name = 'Smith'; -- Note: we only want 'smith'
-- this comment appears after SQL code

The syntax for Transact-SQL
Transact-SQL
Transact-SQL is Microsoft's and Sybase's proprietary extension to SQL. SQL, often expanded to Structured Query Language, is a standardized computer language that was originally developed by IBM for querying, altering and defining relational databases, using declarative statements...

 also supports alternative formats for specifying comments. One format supported by this syntax is identical to the "block comment" style used in the syntax for C++ and Java.

/*
This is a comment line 1
This is a comment line 2
SELECT COUNT(*)
FROM Authors

Haskell

Single line comments in Haskell start with '--' (two dashes), and multiple line comments start with '{-' and end with '-}'.

{- this is a comment
on more lines -}
-- and this is a comment on one line
putStrLn "Wikipedia"

See also

  • Comment
    Comment
    A comment is generally a verbal or written remark often related to an added piece of information, or an observation or statement. These are usually marked with an abbreviation, such as "obs." or "N.B."...

  • Docstring
    Docstring
    In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source...

    , a specific type of comment that is parsed and retained throughout the runtime of the program.
  • HTML comment tag
  • Literate programming
    Literate programming
    Literate programming is an approach to programming introduced by Donald Knuth as an alternative to the structured programming paradigm of the 1970s....

    , alternative documentation paradigm
    Programming paradigm
    A programming paradigm is a fundamental style of computer programming. Paradigms differ in the concepts and abstractions used to represent the elements of a program and the steps that compose a computation A programming paradigm is a fundamental style of computer programming. (Compare with a...

  • Syntax of comments in various programming languages

External links

The source of this article is wikipedia, the free encyclopedia.  The text of this article is licensed under the GFDL.
 
x
OK