An illustration of Java source code with prologue comments indicated in red and inline comments in green. Program code is in blue.

In computer programming, a comment is a programming language construct used to embed information in the source code of a computer program. In most cases, when the source code is processed by a compiler or interpreter, comments are ignored.^[1] Image File history File links No higher resolution available. ... Image File history File links No higher resolution available. ... Java is an object-oriented applications programming language developed by Sun Microsystems in the early 1990s. ... Source code (commonly just source or code) is any series of statements written in some human-readable computer programming language. ... Computer programming (often shortened to programming or coding) is the process of writing, testing, and maintaining the source code of computer programs. ... A programming language is an artificial language that can be used to control the behavior of a machine, particularly a computer. ... The ASCII codes for the word Wikipedia represented in binary, the numeral system most commonly used for encoding computer information. ... Source code (commonly just source or code) is any series of statements written in some human-readable computer programming language. ... This article is about the computing term. ... An interpreter is a computer program that executes other programs. ...

Comments have a wide range of potential uses: from augmenting program code with basic descriptions, to generating extensive documentation.^[2] Comments are also used for integration with source code management systems and other kinds of external programming tools. Documentation generator is a programming tool that generates an API Documentation documentation from a set of specially commented source codes, and in some cases, binary files. ... In Information Technology and telecommunication, the term configuration management has the following meanings: [The] management of security features and assurances through control of changes made to hardware, software, firmware, documentation, test, test fixtures and test documentation of an automated information system, throughout the development and operational life of a system. ... A programming tool is a program or application that software developers use to create, debug, or maintain other programs and applications. ...

Overview

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).^[3] The syntax and rules for these are defined in a programming language specification. 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. ...

Comments are generally formatted as block comments (also called prologue comments) or line comments (also called inline comments).^[4] Block comments are delimited by a sequence of characters that mark the start of the comment and continue until the sequence of characters that mark the end of the comment. Block comments are allowed to span multiple lines of the source code. Typically, block comments do not nest, so any comment start delimiter encountered within a comment body is ignored. Some languages allow nested block comments to facilitate using comments to comment-out blocks of code that may itself contain block comments. 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. Delimiters are marks which are used to seperate subfields of data. ...

Some programming languages employ both block and line comments with different comment delimiters. For example, C++ 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 comments are line comments: they start with -- and continue to the end of the line. C++ (pronounced see plus plus, IPA: ) is a general-purpose, high-level programming language with low-level facilities. ... Ada is a structured, statically typed imperative computer programming language designed by a team led by Jean Ichbiah of CII Honeywell Bull under contract to the United States Department of Defense during 1977–1983. ...

Uses

How best to make use of comments is subject to dispute, different commentators have offered varied and sometimes opposing viewpoints.^[5][6] There are many different ways of writing comments and almost no empirical research on the effectiveness of the different uses.^{[citation needed]}

Code description

Comments can be used to summarise code or to explain the programmer's intent. This is called the why rather than how approach. According to this school of thought, restating the code in plain English is a waste of time; the need to explain the code may be a sign that it is too complex and should be rewritten.

"Don't document bad code – rewrite it" (The Elements of Programming Style, Kernighan & Plauger).

"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." (Code Complete, McConnell)

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: cover for the second edition The Elements of Programming Style, by Brian W. Kernighan the creator of C, is a book about good styles in which programers write their code. ... Brian Wilson Kernighan (IPA pronunciation: , the g is silent), (born 1942 in Toronto, Ontario, Canada) is a computer scientist who worked at Bell Labs alongside Unix creators Ken Thompson and Dennis Ritchie and contributed greatly to Unix and its school of thought. ... P. J. Plauger is a well-known author and entrepreneur. ... Code Complete (ISBN 1556154844) is a 1993 software development book by Steve McConnell urging developers to get past code and fix programming and the big design up front waterfall model. ... Steven Steve C. McConnell is a well-known author of many software engineering textbooks, including: Code Complete editions 1 (1993) & 2 (2004) ISBN 0735619670 Rapid Development (1996) ISBN 0072850604 Software Project Survival Guide (1998) ISBN 1572316217 After the Gold Rush (1999) ISBN 0735608776 Professional Software Development (2004) ISBN 0321193679 His...

 ' Second variable dim because of server errors produced when reuse form data. No ' documentation available on server behavior issue, so just coding around it. 

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 contravenes the why rather than how approach, but may be crucial to those who will be maintaining the code base. This might especially be true in the case of highly-specialized problem domains; or rarely-used optimizations, constructs or function-calls.^[7]

For example, a programmer may add a comment to explain why an insertion sort was chosen instead of a quicksort, as the former is, in theory, slower than the latter. This could be written as follows: Example of insertion sort sorting a list of random numbers. ... Quicksort in action on a list of random numbers. ...

 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

Logos, diagrams, and flowcharts consisting of ASCII art constructions can be inserted into source code formatted as a comment. Additionally, copyright 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. This article or section does not adequately cite its references or sources. ... A simple flowchart for what to do if a lamp doesnt work A flowchart (also spelled flow-chart and flow chart) is a schematic representation of a process. ... ASCII art, an artistic medium relying primarily on computers for presentation, consists of pictures pieced together from characters (preferably from the 95 printable characters defined by ASCII). ... Articles with similar titles include copywrite. ... A binary to text encoding is encoding of data in plain text. ...

Debugging

A common developer practice is to comment out a code snippet as a comment, such that it will not be executed in the final program. For example, one might write: In computing the term commenting out refers to the practice of converting some source code within a file, or the contents of a software configuration file, as comments (often block comments) to a form that has no effect on the execution of a program. ... A Code Snippet is a computer programmers term to refer to small pieces of code that otherwise generally do not function correctly until placed into a larger file of code. ...

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

The above piece of code suggests that the programmer opted to disable the debugging option for some reason.

Automatic documentation generation

Some programming tools read structured information in comments and automatically generate documentation. Automatic documentation generation from the comments in the source code provides a means of maintaining consistency between the documentation of the interface and use of the code. Keeping the documentation within the code makes it easier, and thus more likely, to keep the documentation up to date with changes in the code.

Examples of documenation generators include the javadoc program, designed to be used with the Java programming language, Ddoc for the D programming language and doxygen, to be used with C++, C, Java, IDL and others. Javadoc is a computer software tool from Sun Microsystems for generating API documentation into HTML format from Java source code. ... Java is an object-oriented applications programming language developed by Sun Microsystems in the early 1990s. ... Ddoc is the embedded documentation generator for the D programming language. ... D is an object-oriented, imperative system programming language designed by Walter Bright of Digital Mars as a re-engineering of C/C++. He has done this by re-designing many C++ features, and borrowing ideas from other programming languages. ... Doxygen is a documentation generator for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, D and ActionScript. ... C++ (pronounced see plus plus, IPA: ) is a general-purpose, high-level programming language with low-level facilities. ... C is a general-purpose, procedural, imperative computer programming language developed in 1972 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system. ... An interface description language (or alternately, interface definition language), or IDL for short, is a computer language used to describe a software components interface. ...

C# implements a similar feature called "XML Comments" which are read by IntelliSense from the compiled .NET assembly. The next revision of Visual Basic will also feature this. C# (pronounced see-sharp) is an object-oriented programming language developed by Microsoft as part of their . ... Screenshot of IntelliSense in Visual C++ IntelliSenseâ„¢ is a feature popularized by the Microsoft Visual Studio Integrated Development Environment. ... The Microsoft . ... Visual Basic (VB) is an event driven programming language and associated development environment from Microsoft for its COM programming model. ...

Metadata and annotations

Developer tools sometimes store metadata in comments, such as insert positions for automatic header file inclusion, commands to set the file's syntax highlighting mode, or the file's revision number. These functional control comments are commonly referred to as annotations. A programming tool is a program or application that software developers use to create, debug, or maintain other programs and applications. ... Metadata (Greek meta after and Latin data information) are data that describe other data. ... HTML syntax highlighting Syntax highlighting is a feature of some text editors that displays text—especially source code—in different colors and fonts according to the category of terms. ... Revision control (also known as version control, source control or (source) code management (SCM)) is the management of multiple revisions of the same unit of information. ... Annotation is extra information associated with a particular point in a document or other piece of information. ...

Comments are often employed for these and related methods because they allow the use of syntax and lexical conventions that might otherwise conflict with those of the enclosing programming language. This is another sense in which it is helpful that compilers and interpreters "ignore" comments.

Warnings

Some comments are intended as warnings to other programmers that code may not be complete or may have known limitations which should be addressed. One convention for such comments is to prefix them with XXX in order to allow ease of later identifications of potential problems.^[8]

Philosophy

There are various normative and philosophical approches regarding the proper use of comments in source code.

Necessity of comments

Some contend that comments are unnecessary because well-written source should be self explanatory; others contend that source 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). For information on the programming language, see Whitespace programming language. ...

In between these views is the philosophy that comments are neither beneficial nor harmful by themselves, and what matters is that they are correct and kept in synch with the source code, and omitted if they are superfluous, excessive, difficult to maintain or otherwise unhelpful.^[9]

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 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" as described previously in this article.

Offensive comments

Sometimes comments in source code are used as a way to relieve stress or to speak unfavorably about development tools, competitors, employers, or working conditions. 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.^[10] The occurrence of this phenomenon can be easily seen from online resources that track profanity in source code.^[11] Look up Profanity in Wiktionary, the free dictionary. ...

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.^[12] In computer security, the word vulnerability refers to a weakness in a system allowing an attacker to violate the confidentiality, integrity, availability [i. ...

Styles

Stylistically, comments can appear in source code in various ways: as brief end-of-line remarks to explain or document a single line of code; as one-line descriptions that preceed or follow a line of source code; or as multi-line paragraphs that document something between adjacent code blocks. A common use for a paragraph comment is to explain in some detail what the following block of code statements does.

Comment styles are often agreed upon before a project starts. Usually programmers prefer styles that are consistent, non-obstructive, easy to modify, and difficult to break.

For example, C-style comments could look like this

 /* This is the comment body. */ 

or maybe this

 /*************************** * * * This is the comment body. * * * ***************************/ 

If a programmer's editor doesn't manage the second variant automatically, it may discourage changes to the comments, thus leading to comments which are out of date with respect to the code. On the other hand, some may recommend the second comment variant because its visual appearance may contrast well with the rest of the code, or for personal stylistic preference.

At least one commentator^[13] 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. */ 

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 approach 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).

Certain projects try to define rules like "one comment every ten lines". They can be counterproductive when adhered to with too much rigor, but might still be of use when one wants to quickly judge after writing a body of code whether one needs to check if enough comments are in place.

Tags

Certain tags are used in comments to assist in indexing common issues. Such tags can be searched with common programming tools, such as the UNIX grep utility. For a proposal for tagging in Wikipedia, see Wikipedia:WikiProject Microformats#MediaWiki issues A tag cloud with terms related to Web 2. ... Filiation of Unix and Unix-like systems Unix (officially trademarked as UNIX®) is a computer operating system originally developed in the 1960s and 1970s by a group of AT&T employees at Bell Labs including Ken Thompson, Dennis Ritchie and Douglas McIlroy. ... grep is a command line utility that was originally written for use with the Unix operating system. ...

• FIXME is used to mark potential problematic code that requires special attention and/or review.
• NOTE is used to document inner workings of code and indicate potential pitfalls.
• TODO is used to indicate planned enhancements.

Examples

Comparison

See main article: Programming Language Comparison: Comments.

The typographical conventions for specifying comments varies widely. Additionally, individual programming languages sometimes provide unique variants. For a detailed review, please consult the programming language comparison article. // Programming language statements typically have conventions for: statement separators; statement terminators; and line continuation A statement separator is used to demarcate boundaries between two separate statements. ... // Programming language statements typically have conventions for: statement separators; statement terminators; and line continuation A statement separator is used to demarcate boundaries between two separate statements. ...

In-context

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; 

(This is from the fork.c file from the Linux kernel source.) The Linux kernel is a Unix-like operating system kernel. ...

Classic BASIC

 10 REM This is a classic BASIC program for novice programmers. 15 REM It prints the word "WIKIPEDIA" on screen. 20 PRINT "WIKIPEDIA" 30 GOTO 20 

Fortran 90

 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Any non-numeric character in the first column comments out * * the entire line. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * PRINT "WIKIPEDIA" ! All characters after an exclamation ! mark are an inline comment. END 

Java

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

(From the Sun Microsystems javadoc documentation. The comment is designed to be read by the javadoc processor.) Sun Microsystems, Inc. ... Javadoc is a computer software tool from Sun Microsystems for generating API documentation into HTML format from Java source code. ...

Unique variants

Some developers have either implemented or begun work on providing alternate modalities for specifying comments in source code. This type of extension is possible since any type of resource can be specified in text (given the proper encoding), and because Integrated Development Environments provide increasingly flexible options for linking to related external content. It has been suggested that IDE-style interface be merged into this article or section. ...

Audio comments

One example of this variability of comment types is the use of audio files to include voice annotations in source code.^[14]

See also

• Comment (computing) for a general discussion on the use of comments in computing.
• Docstring, a specific type of comment that is parsed and retained throughout the runtime of the program

In computing, a comment is information in a file that is generally ignored but may be helpful to human users of the file. ... In programming, a docstring is a comment included in source code to document the purpose of a piece of code. ...

Notes and references

1. ^ Comments must be indicated in a way that allows a source code processor to recognize them as such. This is often simplified by saying comments are "ignored" (after they have been recognized) by the processor.
2. ^ Comments can be processed in various ways to generate documentation. See e.g., Comparison of documentation generators.
3. ^ Penny Grubb, Armstrong Takang (2003). Software Maintenance: Concepts and Practice. World Scientific. ISBN 981238426X. 
4. ^ Dixit, J.B. (2003). Computer Fundamentals and Programming in C. Laxmi Publications. ISBN 8170088828. 
5. ^ W. R., Dietrich (2003). Applied Pattern Recognition: Algorithms and Implementation in C++. Springer. 3528355581.  offers viewpoints on proper use of comments in source code. p. 66.
6. ^ Keyes, Jessica (2003). Software Engineering Handbook. CRC Press. 0849314798.  discusses comments and the "Science of Documentation" p. 256.
7. ^ Spinellis, Diomidis (2003). Code reading: The Open Source Perspective. Addison-Wesley. ISBN 0201799405. 
8. ^ Arensburger, Andrew (2001-03-27). /* You Are Expected to Understand This */ (editorial). freshmeat.net.
9. ^ Dewhurst, Stephen C (2002). C++ Gotchas: Avoiding Common Problems in Coding and Design. Addison-Wesley Professional. ISBN 0321125185. 
10. ^ Doar, Matthew B. (2005). Practical Development Environments. O'Reilly. ISBN 0596007965. 
11. ^ (see e.g., http://www.vidarholen.net/contents/wordcount/ Linux Swear Count, http://www.google.com/codesearch?hl=en&lr=&q=fucking Google Code Search).
12. ^ Andress, Mandy (2003). Surviving Security: How to Integrate People, Process, and Technology. CRC Press. ISBN 0849320429. 
13. ^ Allen Holub, Enough Rope to Shoot Yourself in the Foot, ISBN 0-07-029689-8, 1995, McGraw-Hill
14. ^ http://dev.devbiz.com/blogs/hakan/archive/2005/08/03/voice_comments.aspx Voice Comments

The following tables compare general and technical information for a number of documentation generators. ... 2001 (MMI) was a common year starting on Monday of the Gregorian calendar. ... March 27 is the 86th day of the year in the Gregorian calendar (87th in leap years). ...

External links

• How to Write Comments by Denis Krukovsky
• How to Write Comments for the Javadoc Tool
• Doxygen, a documentation system for C, C++, Java, Objective-C, Python, IDL and to some extent PHP, C#, and D