Comment (computer programming)

From Wikipedia, the free encyclopedia
Jump to: navigation, search
For comments in Wikipedia markup, see Help:Wiki markup#Character formatting and WP:COMMENT.
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[1] used to embed programmer-readable annotations in the source code of a computer program.[2] Those annotations are potentially significant to programmers but are generally ignored by compilers and interpreters.[3][4] 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 (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.[5] Comments are also used for integration with source code management systems and other kinds of external programming tools.

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[edit]

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

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) allow block comments to be recursively nested inside one another, but others (such as Java) do not.[7][8][9]

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.[9]

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.[9]

Uses[edit]

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

Planning and reviewing[edit]

Comments can be used as a form of pseudocode 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[edit]

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."[12]
"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."[13]

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[edit]

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.[14]

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:

 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[edit]

Logos, diagrams, and flowcharts consisting of ASCII art constructions can be inserted into source code formatted as a comment.[15] Further, 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.

The following code fragment is a simple ASCII diagram depicting the process flow for a system administration script contained in a Windows Script File running under Windows Script Host. Although a section marking the code appears as a comment, the diagram itself actually appears in an XML CDATA section, which is technically considered distinct from comments, but can serve similar purposes.[16]

<!-- begin: wsf_resource_nodes -->
<resource id="ProcessDiagram000">
<![CDATA[
 HostApp (Main_process)
    |
    V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
                |
                |
                V
         mru.ini (mru_history)   
]]>
</resource>

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.[16]

Debugging[edit]

"Comment out" redirects here.

A common developer practice is to comment out a code snippet, 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.

Many IDEs allow quick adding or removing such comments with single menu options or key combinations. The programmer has only to mark the part of text they want to (un)comment and choose the appropriate option. It is useful with large parts of code.

Automatic documentation generation[edit]

Programming tools sometimes store documentation and metadata in comments.[17] These may include insert positions for automatic header file inclusion, commands to set the file's syntax highlighting mode,[18] or the file's revision number.[19] These functional control comments are also commonly referred to as annotations. 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.[20]

Examples of documentation generators include the programs Javadoc for use with Java, Ddoc for D, Doxygen for C, C++, Java, IDL, and PHPDoc for PHP.

C#, F# and Visual Basic implement a similar feature called "XML Comments" which are read by IntelliSense from the compiled .NET assembly.[21]

Normative views[edit]

There are various normative views and long-standing opinions regarding the proper use of comments in source code.[22] Some of these are informal and based on personal preference, while others are published or promulgated as formal guidelines.[23]

Need for comments[edit]

Technical commentators have documented varying viewpoints on whether and when comments are appropriate in source code.[12] [24] Some commentators assert that source code should be written with few comments, on the basis that the source code should be self-explanatory.[12] 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).[25][26]

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.[27][28]

Level of detail[edit]

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."[13] Further, for professional coding environments, the level of detail is ordinarily well-defined to meet a specific performance requirement defined by business operations.[26]

Offensive comments[edit]

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. The occurrence of this phenomenon can be easily seen from online resources that track profanity in source code.[29]

Comments in web templates[edit]

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.[30]

Styles[edit]

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.[31]

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 editors that can automate the alignment and visual appearance of text in comments.

Software consultant and technology commentator Allen Holub[32] is one expert who advocates aligning the left edges of comments:[33]

 /* 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[edit]

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[edit]

Certain tags are used in comments to assist in indexing common issues. Such tags are commonly syntax-highlighted within text editors and can be searched for with common programming tools, such as the Unix grep 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.[34]

Examples[edit]

Comparison[edit]

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.

In context[edit]

AppleScript[edit]

This section of AppleScript code shows the two styles of comments used in that language.

(*
This program displays a greeting.
*)
on greet(myGreeting)
     display dialog myGreeting & " world!"
end greet
 
-- Show the greeting
greet("Hello")

BASIC[edit]

This BASIC 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 phrase "HELLO"
20 PRINT "HELLO"
30 GOTO 20

When run, this program repeatedly prints the word "HELLO" (without quotes) in an infinite loop.

In Microsoft BASICs, including QuickBasic, Qbasic, Visual Basic and Visual Basic .NET, or descendants such as FreeBASIC or Gambas, any text on a line after an ' (apostrophe) character is placed is marked as a comment. Lines that begin with 'REM' (for 'remark') are treated as comments as well, similar to other BASIC dialects. Following is an example in Visual Basic .NET:

Public Class Form1
    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        ' The following code is executed when the user
        ' clicks the button in the program's window.
 
        MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting
    End Sub
End Class

C[edit]

This C code fragment demonstrates the use of a prologue comment or "block comment" to describe the purpose of a conditional statement. 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 source.

ColdFusion[edit]

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

 <!--- This prints "Hello World" to the browser. --->
 <cfoutput>
   Hello World<br />
 </cfoutput>

Fortran IV[edit]

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[edit]

This Fortran 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 *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
    print '(A)', 'I <3 WIKIPEDIA!' ! Fortran 90 introduced the option for inline comments.
end program

Haskell[edit]

Single line comments in Haskell start with '--' (two hyphens), 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"

Haskell also provides a literate programming method of commenting known as "Bird Style"; to encourage the use of comments to generate documentation, the code is marked with a leading '>' on each line instead of marking the comments:

This code simply outputs the word "Wikipedia" to the current output. It serves as an example of "Bird Style" Haskell code.
The code itself follows after this paragraph and a blank line.
 
> putStrLn "Wikipedia"

Java[edit]

This Java code fragment shows a block comment used to describe the setToolTipText method. The formatting is consistent with Sun Microsystems Javadoc 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) {

OCaml[edit]

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

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

Perl[edit]

Line comments in Perl, and many other scripting languages, begin with a hash (#) symbol. A comment at the beginning, called the shebang, tells the system what interpreter to use.

#!/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, a markup language for literate programming,[35] for instance:[36]

=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 });
 
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[edit]

Comments in PHP can be either in C++ style (both inline and block), or use hashes. PHPDoc is a style adapted from Javadoc and is a common standard for documenting PHP code.

PowerShell[edit]

Comments in Windows PowerShell

# Single line comment
Write-Host "Hello, World!"
 
<# Multi
   Line
   Comment #>
Write-Host "Goodbye, world!"

Python[edit]

Comments in Python use the hash character. This Python program starts with #! (a so-called “shebang”) to tell the operating system which interpreter to use.

#!/usr/bin/env python
 
# this program prints "Hello World" to the screen and then quits. 
print "Hello World!"

Python also supports docstrings, 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[edit]

Comments in Ruby.

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

puts "This is not a comment"
 
#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"
 
=begin
 
whatever goes in here
 
will be ignored :)
 
=end
 
puts "This is not a comment"

SQL[edit]

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 also supports alternative formats for specifying comments.[37] 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

VBScript[edit]

This VBScript code fragment demonstrates how comments are used in that language. This style of commenting derives from BASIC.

' This is a comment in VBScript.
' This is another comment in VBScript.
' Any text from a single quote to the newline character is a comment.

See also[edit]

Notes and references[edit]

  1. ^ For purposes of this article, programming language comments are treated as indistinct from comments that appear in markup languages, configuration files and other similar contexts. Moreover, markup language is often closely integrated with programming language code, especially in the context of code generation. See e.g., Ganguli, Madhushree (2002). Making Use of Jsp. New York: Wiley. ISBN 0-471-21974-6. , Hewitt, Eben (2003). Java for Coldfusion Developers. Upper Saddle River: Pearson Education. ISBN 0-13-046180-6. 
  2. ^ 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).Penny Grubb, Armstrong Takang (2003). Software Maintenance: Concepts and Practice. World Scientific. pp. 7, 120–121. ISBN 981-238-426-X. 
  3. ^ Some programming environments include comments as one element of the language syntax that is retained for further processing, instead of discarded once recognized by the language processor.
  4. ^ 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 and discarded) by the processor.
  5. ^ Comments can be processed in various ways to generate documentation external to the source code itself. See e.g., Comparison of documentation generators.
  6. ^ Dixit, J.B. (2003). Computer Fundamentals and Programming in C. Laxmi Publications. ISBN 81-7008-882-8. 
  7. ^ Higham, Desmond (2005). MATLAB Guide. SIAM. ISBN 0-89871-578-4. 
  8. ^ Vermeulen, Al (2000). The Elements of Java Style. Cambridge University Press. ISBN 0-521-77768-2. 
  9. ^ a b c "Using the right comment in Java". Retrieved 2007-07-24. 
  10. ^ W. R., Dietrich (2003). Applied Pattern Recognition: Algorithms and Implementation in C++. Springer. ISBN 3-528-35558-1.  offers viewpoints on proper use of comments in source code. p. 66.
  11. ^ a b Keyes, Jessica (2003). Software Engineering Handbook. CRC Press. ISBN 0-8493-1479-8.  discusses comments and the "Science of Documentation" p. 256.
  12. ^ a b c The Elements of Programming Style, Kernighan & Plauger
  13. ^ a b Code Complete, McConnell
  14. ^ Spinellis, Diomidis (2003). Code reading: The Open Source Perspective. Addison-Wesley. ISBN 0-201-79940-5. 
  15. ^ "CodePlotter 1.6 - Add and edit diagrams in your code with this 'Visio-like' tool". Retrieved 2007-07-24. 
  16. ^ a b Niederst, Jennifer (2006). Web Design in a Nutshell: A Desktop Quick Reference. O'Reilly. ISBN 0-596-00987-9. Sometimes the difference between a "comment" and other syntax elements of a programming or markup language entails subtle nuances. Niederst indicates one such situation by stating: "Unfortunately, XML software thinks of comments as unimportant information and may simply remove the comments from a document before processing it. To avoid this problem, use an XML CDATA section instead."
  17. ^ See e.g., Wynne-Powell, Rod (2008). Mac Os X for Photographers: Optimized Image Workflow for the Mac User. Oxford: Focal Press. ISBN 0-240-52027-0.  page 243
  18. ^ Lamb, Linda (1998). Learning the VI Editor. Sebastopol: O'Reilly & Associates. ISBN 1-56592-426-6.  describes the use of modeline syntax in Vim configuration files.
  19. ^ See e.g., Berlin, Daniel (2006). Practical Subversion, Second Edition. Berkeley: APress. ISBN 1-59059-753-2.  page 168.
  20. ^ Ambler, Scott (2004). The Object Primer: Agile Model-Driven Development with UML 2.0. Cambridge University Press. ISBN 1-397-80521-8. 
  21. ^ Murach. C# 2005. p. 56. 
  22. ^ Goodliffe, Pete (2006). Code Craft. San Francisco: No Starch Press. ISBN 1-59327-119-0. , Smith, T. (1991). Intermediate Programming Principles and Techniques Using Pascal. Belmont: West Pub. Co. ISBN 0-314-66314-2. 
  23. ^ See e.g., Koletzke, Peter (2000). Oracle Developer Advanced Forms & Reports. Berkeley: Osborne/McGraw-Hill. ISBN 0-07-212048-7.  page 65.
  24. ^ "Worst Practice - Bad Comments". Retrieved 2007-07-24. 
  25. ^ Morelli, Ralph (2006). Java, Java, Java: object-oriented problem solving. Prentice Hall College. ISBN 0-13-147434-0. 
  26. ^ a b "How to Write Doc Comments for the Javadoc Tool". Retrieved 2007-07-24.  Javadoc guidelines specify that comments are crucial to the platform. Further, the appropriate level of detail is fairly well-defined: "We spend time and effort focused on specifying boundary conditions, argument ranges and corner cases rather than defining common programming terms, writing conceptual overviews, and including examples for developers."
  27. ^ Yourdon, Edward (2007). Techniques of Program Structure and Design. University of Michigan. 013901702X. Non-existent comments can make it difficult to comprehend code, but comments may be detrimental if they are obsolete, redundant, incorrect or otherwise make it more difficult to comprehend the intended purpose for the source code.
  28. ^ Dewhurst, Stephen C (2002). C++ Gotchas: Avoiding Common Problems in Coding and Design. Addison-Wesley Professional. ISBN 0-321-12518-5. 
  29. ^ (see e.g., Linux Swear Count).
  30. ^ Andress, Mandy (2003). Surviving Security: How to Integrate People, Process, and Technology. CRC Press. ISBN 0-8493-2042-9. 
  31. ^ "Coding Style". Retrieved 2007-07-24. 
  32. ^ "Allen Holub". Retrieved 2007-07-24. 
  33. ^ Allen Holub, Enough Rope to Shoot Yourself in the Foot, ISBN 0-07-029689-8, 1995, McGraw-Hill
  34. ^ "TODO or not TODO". Retrieved 2009-02-08. 
  35. ^ "perlpod - the Plain Old Documentation format". Retrieved 2011-09-12. 
  36. ^ "Pod::ParseUtils - helpers for POD parsing and conversion". Retrieved 2011-09-12. 
  37. ^ Talmage, Ronald R. (1999). Microsoft SQL Server 7. Prima Publishing. ISBN 0-7615-1389-2. 


Further reading[edit]

External links[edit]