Comments: Difference between revisions
Undo revision 15649 by 222.240.212.17 (Talk) What the spam? |
|||
Line 2:
Demonstrate all ways to include text in a language source file which is completely ignored by the compiler or interpreter.
=={{header|4D}}==
`Comments in 4th Dimension begin with the accent character and extend to the end of the line.
=={{header|ActionScript}}==
|
Revision as of 01:30, 20 May 2008
![Task](http://static.miraheze.org/rosettacodewiki/thumb/b/ba/Rcode-button-task-crushed.png/64px-Rcode-button-task-crushed.png)
You are encouraged to solve this task according to the task description, using any language you may know.
Demonstrate all ways to include text in a language source file which is completely ignored by the compiler or interpreter.
4D
`Comments in 4th Dimension begin with the accent character and extend to the end of the line.
ActionScript
- See Java
Ada
-- All Ada comments begin with "--" and extend to the end of the line
ALGOL 68
Comments can be inserted in variety of ways:
¢ The original way of adding your 2 cents worth to a program ¢ comment "bold" comment comment co Style i comment co # Style ii comment # £ This is a hash/pound comment for a UK keyboard £
BASIC
100 REM Standard BASIC comments begin with "REM" (remark) and extend to the end of the line
'this is a comment PRINT "this is code"
Befunge
Like Brainfuck, all characters and whitespace which are not commands are ignored. Most punctuation, digits, and 'g' and 'p' are commands.
Also, since the code/data-space is two-dimensional, comments can be placed anywhere that will be untouched by the instruction pointer and data access commands.
& read a number 2+ add two .@ display result and exit ^- inline comments -^ <-^- other comments
Brainf***
This is a comment
Most ASCII characters may be used for comments; only the eight characters "+-<>[],." are Brainf*** commands. Extra care much be used when using punctuation, particularly the comma or period. These are I/O operators and are actual commands rather than comments, and are instead compiled into the program if used and may have to be "debugged" and removed if you forget this issue.
C
/* This is a comment. */ /* So is this multiline comment. */
The comment starts at the /*, and ends at the */. A comment may be used between any tokens. It cannot be used inside tokens, that is, given the code
struct charisma {}; void f(char/* comment */isma) {}
the function takes an argument of type char, named isma, not an unnamed argument of type charisma.
Comments cannot be nested; that is, if you write
/* some comment /* trying to nest some other comment */ inside */
the comment ends at the first */, and inside */ is again interpreted as source code (almost certainly causing a compile error). Some compilers have the option to allow nested comments, but this is not a standard feature.
Conditional compilation also can be used to make the compiler ignore some text:
#if 0 While technically not a comment, this is also ignored by the compiler #endif
The trick is that 0 is always false, therefore the text between #if 0 and #endif is never compiled. While this should never be used for actual comments, it's an easy way to comment out some code, especially because it doesn't interfere with normal (documentation) comments.
Conditional compile "comments" can be nested:
#ifdef UNDEFINED This is not compiled. #if 0 Nor is this. #endif And this still is not compiled. #endif
Even though the compiler doesn't see #if 0 text, the preprocessor does. Therefore some minimal rules still have to be followed. For example, the following code is not valid:
#if 0 This isn't valid. #endif
That's because the preprocessor will interpret the apostrophe as beginning of a character constant, and will complain because that character constant isn't terminated with another apostrophe.
Note that the problem mentioned above cannot occur if there's valid code between the #if 0 and #endif.
// C++ single-line comments were adopted in the C99 standard.
C++
- See also C
Single line C++-style comments
// This is a comment
C++-style comments start with // and reach up to, but not including, the end of line (more exactly, up to the next unescaped newline). While formally, C++-style comments cannot be nested either, in practice they can:
// This is a valid comment // with a "nested" comment
That's because starting with the first // everything in the line is ignored, including the second //. The fact that the newline is not part of the comment is important for multi-line macro definitions. It means that in the code
#define FOO \ (macro text) // comment (no more macro text)
the line (no more macro text) is not part of the macro definition. Also escaping the line break at the end of the comment with '\' doesn't help, because that would make the third line part of the comment instead. Comments inside macros therefore have to be C-style.
Clean
Clean comments are similar to C++.
Start = /* This is a multi- line comment */ 17 // This is a single-line comment
In contrast to C++ comments can be nested.
Start = /* This is a comment /* Nested comment */ still a comment */ 17
Common Lisp
Common Lisp provides line comments (;
) and block comments (#|...|#
).
Block comments can nest (#|...#|...|#...|#
), unlike block comments in e.g. C.
In a common convention, header comments are prefaced with four semicolons, top-level (function level) comments use three, comments for sections of code use two, and margin comments use one.
;;;; This code implements the foo and bar functions ;;; The foo function calls bar on the first argument and multiplies the result by the second. ;;; The arguments are two integers (defun foo (a b) ;; Call bar and multiply (* (bar a) ; Calling bar b)) ;;; The bar function simply adds 3 to the argument (defun bar (n) (+ n 3))
However, comments should not be used for inline documentation, as most defining constructs permit a documentation string (which is then available at runtime).
(defun bar (n) "Add 3 to the argument." (+ n 3)) (defclass button (widget) (label action) (:documentation "This is a push-button widget."))
Delphi
- See also Pascal
In addition, Delphi also allows C++ style single line comments:
// single line comment
E
# This is a regular comment.
? "This is an Updoc comment, which > is an executable example or test case.".split(" ") # value: ["This", "is", "an", "Updoc", "comment,", "which # is", "an", "executable", "example", "or", "test", "case."]
Erlang
% Erlang comments begin with "%" and extend to the end of the line.
Forth
Standard Forth includes a number of ways to add comment text. As with everything in Forth, comment characters are actually words that control the compiler.
\ The backslash skips everything else on the line ( The left paren skips everything up to the next right paren on the same line)
Traditionally, the paren comments are used for "stack effect" notation:
: myword ( a b -- c ) ...
This comment means "myword takes two cells on the stack and leaves one". Sometimes, stack effect comment names give clues about the word's function:
: add'em ( a b -- a+b ) + ; : strlen ( addr -- len ) count nip ;
Some Forth systems implement other commenting words, such as these words from Win32Forth:
\s skips all remaining text in the file (( skips until the next double-paren, stretching across multiple lines )) comment: Ignore all text in this section comment; doc Another comment block enddoc /* C-style comment */ (* Pascal-style comment *)
Fortran
Compiler: ANSI FORTRAN 77 or compatible (like g77 -strict)
The first six columns in Fortran are traditionally reserved for labels and certain special characters. In particular the letter "C" in the first column indicates a comment:
C This would be some kind of comment C Usually one would avoid columns 2-6 even in a comment.
Some Fortran compilers have the extension that comments starting with D are treated as non-comments if a special debugging flag is given at the compiler invocation. For example:
C If compiled in debugging mode, print the current value of I D PRINT *, I
ISO Fortran 90 or later have an inline comment (!) syntax:
real :: a = 0.0 ! initialize A to be zero
In ISO Fortran 90 or later, "C in first column" comments are only allowed in the "fixed" source form familiar to FORTRAN 77 programmers. The "free" source form only has inline comments (!}.
ISO Fortran 95 or later has an optional conditional compilation syntax. If present, it can be used (abused?) to (in effect) comment out blocks of code:
?? if (.false.) then do while (oh_no) a = bad_news() b = big_mistake() c = gigo() end do ?? end if
Haskell
i code = True -- I am a comment. {- I am also a comment. {-comments can be nested-} let u x = x x (this code not compiled) Are you? -}
IDL
The comment character in IDL is the semicolon - everything starting with it and to the end of the line is a comment. Like this:
; The following computes the factorial of a number "n" fact = product(indgen( n )+1) ; where n should be an integer
J
NB. Text that follows 'NB.' has no effect on execution.
0 $ 0 : 0 Multi-line comments may be placed like this. ) Note 'example' Another way to record multi-line comments as text is to use 'Note', which is actually a simple program that makes it clearer when defined text is used only to provide comment. )
Java
Java has two ways to enter comments.
/* This is a comment */
/* * This is * a multiple * line comment. */
This C-style comment starts with /* and ends with */. The two delimiters may be on the same or separate lines. This style comment may be used anywhere white space is permitted.
// This is a comment
This C++-style comment starts with // and extends to the end of line.
/** This is a Javadoc comment */
/** * This is * a multiple * line Javadoc comment */
Javadoc is a standardized documentation code for Java. Its comments begin with a forward slash and two stars. Javadoc comments have different tags that signify different things in the methods and classes that they precede.
JavaScript
- See Java
LaTeX
In LaTeX, comments look like this:
% This is a comment
LaTeX comments start with % and continue up to and including the line break. The fact that the line break itself is commented out as well makes it useful for adding line breaks in the source code of complex macros without LaTeX interpreting them (which may cause extra space or even a paragraph break in the resulting typeset text). For example, the following results in the one word "understandable":
\newcommand{\firstpart}{understand} \newcommand{\secondpart}{able} \newcommand{\complete}{% \firstpart% \secondpart} \complete
Without the percent sign after \firstpart, it would have been the two words "understand able".
Lisp
; This is a single-line comment.
#|| This is a multiline comment ||#
(defun foo () "This function has a documentation string." (do-something))
Documentation strings are optional and may span multiple lines as string literals do. In addition to defun, many other constructs may also include documentation strings. Among these are defmacro, defmethod, defstruct, defclass, defvar, defparameter, and defconstant.
Logo
; comments come after a semicolon, and last until the end of the line
LotusScript
LotusScript has two ways to enter comments.
' This is a comment
Wherever the single quote (') is used, the rest of the line is treated as a comment and ignored. Multi-line comments would each need a single quote mark. This style of comment is usually used for making small in-line or single line comments.
%REM This is a multi- line comment. %END REM
A %REM marker begins a comment block, and a %END REM marker ends the comment block. This style of comment is used for making longer multi-line comments, often at the beginning of a class, sub or function.
LSE64
# single line comment (space after # is required)
The author of LSE comments the stack effect of words with header comments as follows:
# arg1 arg2 yields result|nothing
Lua
-- A single line comment
--[[A multi-line comment --]]
MAXScript
-- Two dashes precede a single line comment
/* This is a multi-line comment */
Objective-C
- See C
OCaml
(* This a comment (* containing nested comment *) *)
Pascal
(* This is a comment. It may exend across multiple lines. *) { Alternatively curly braces can be used. } (* This is a valid comment in Standard Pascal, but not valid in Turbo Pascal. } { The same is true in this case *)
In Pascal, comments cannot be nested.
Perl
Single line comment
# this is commented
These may also be at the end of a line
my $var = 1; # this is the comment part
Multi-line comments for inline documentation (Plain Old Documentation, or POD in Perl parlance) follow the format:
=pod
Here are my comments this is multi-line
=cut
Note that technically, both of the lines beginning with the equals sign must be surrounded on either side for compatibility with all "POD" parsers.
Note also that any string beginning with an equals sign, and that appears in the initial column of a line, begins a multi-line comment. It does not have to be a POD "command:" the following are all valid:
=head1 =head4 =over 4 =Any Old String
Such blocks always end in =cut.
For more info, type at a command prompt (or into a search engine): "perldoc perlpod"
PHP
Single line comment:
# this is commented // this is commented
These may also be at the end of a line:
$var = 1; # this is the comment part $var = 1; // this is the comment part
Basic syntax for multi-line comments:
/* Here are my comments this is multi-line */
Note that; it is more common to see phpDocumentor styled multi-lined comments:
/** * phpdoc Comments * @todo this is a todo stub */
Pop11
Pop11 has two kinds of comments: endline and C-like. Endline comment begins with tree consecutive semicolons and ends at the end of line:
;;; This is a comment
C-like comments may be multiline:
/* First line Second line */
C-like comments (unlike C) may be nested:
/* This is a comment /* containing nested comment */ */
One can also use conditional compilation to comment out sections of code
#_IF false some code #_ENDIF
however, commented out part must consist of valid Pop11 tokens. In particular, C-like comments must balance and strings must be terminated. The following is an error:
#_IF false This w'ont work #_ENDIF
because apostrophe starts an unterminated string.
PowerShell
PowerShell uses "#" to indicate that the rest of a line is a comment.
Python
Python uses the "#" symbol to mark it's comments. After placing a "#", everything in that line will be ignored.
# This is a comment foo = 5 # You can also append comments to statements
"""Strings in triple-double quotes can be used as quotes """
''' "triple quoted strings" can be delimited by either 'single' or "double" quote marks; and they can contain mixtures of other quote marks without any need to \escape\ them using any special characters. They also may span multiple lines without special escape characters. '''
Note that strings inserted among program statements in Python are treated as expressions (which, in void context, do nothing). Thus it's possible to "comment out" a section of code by simply wrapping the lines in "triple quotes" (three consecutive instances of quotation marks, or of apostrophes, and terminated with a matching set of the same).
Documentation Strings
Python makes pervasive use of strings which immediately follow class and function definition statements, and those which appear as the first non-blank, non-comment line in any module or program file. These are called "documentation" strings or "docstrings" for short; and they are automatically associated with the __doc__ attribute of the class, function, or module objects in which they are defined. Thus a fragment of code such as:
#!/usr/bin/env python # Example of using doc strings """My Doc-string example" class Foo: '''Some documentation for the Foo class''' def __init__(self): "Foo's initialization method's documentation" def bar(): """documentation for the bar function""" if __name__ == "__main__": import sys print __doc__, __main__.__doc__, Foo.__doc__, Foo.__init__.__doc__, bar.__doc__
... would print each of the various documentation strings in this example. (In this particular example it would print two copies of the first doc string which because __doc__ in the "current" name space is the same as __main__.__doc__ when our program is running as a script). If some other script were to import this file (under the name "example" perhaps) then "My Doc-string example" would be the value of example.__doc__
Python "docstrings" are used by a number of tools to automatically generate documentation (for most of the Python standard libraries, classes, functions, etc, as well as for user programs which define docstrings). They are also used by tools such as doctest to automatically derive test suites from properly formatted examples of class instantiations, function invocations and other usage samples. The standard pydoc utility can search through Python source trees generating documentation and can function as a local web server allowing a programmer to browse "live" hyperlinked documentation of their project.
(As noted above extraneous strings interspersed throughout a Python source file can be used as comments, though this is rarely done in practice; only those strings which lexically follow the definition of a class, function, module or package are assigned to __doc__ attributes in their respective name spaces).
Raven
# this is a comment
Ruby
x = "code" # I am a comment =begin hello I am comment =end puts "code"
Scheme
; Basically the same as Common Lisp
Seed7
# A single line comment
(* A multi-line comment *)
(* In Seed7, (* comments can be nested. *) *)
Smalltalk
"Comments traditionally are in double quotes." "Multiline comments are also supported. Comments are saved as metadata along with the source to a method. A comment just after a method signature is often given to explain the usage of the method. The class browser may display such comments specially."
SNUSP
As with Brainfuck and Befunge, any character that is not part of the language is ignored and can be used as commentary, and you can add comments anywhere the instruction pointer is not expected to traverse. Reserved characters are:
- Core: + - > < , . ? ! / \ $ #
- Modular: @ #
- Bloated: : ; & %
As a matter of convention, the characters '=' and '|' are used for spacing to indicate horizontal and vertical flow of control, respectively.
Tcl
Tcl follows the usual scripting language rules: a comment starts at a "#" symbol, which can be placed after a command if that is terminated by a semicolon:
# comment on a line by itself. The next is a command by itself: set var1 $value1 set var2 $value2 ; # comment that follows a line of code
TCL has no native multi-line comment format. However, in most circumstances, a multi-line comment can be faked by wrapping it within a block:
if 0 ( Comments... )
Toka
There are two ways to add comments in Toka. For full lines, or at the end of a line, the shebang is normally used:
#! Everything on this line (after the shebang to the left) will be ignored.
The shebang comments can not be used inside of functions.
In addition, Toka also accepts parenthetical comments. These are enclosed in parenthesis, and are often used for stack comments or comments inside functions.
[ ( a b -- c ) ... ] is myword
In addition, parenthetical comments can span multiple lines.
( This is a simple, multi-line comment )
Since comments are provided by actual functions, the comment function must be whitespace delimited, just as with all other functions in Toka.
A final way to include text in a file is to mark a false ending with end.
... code .... end. Nothing following the end. will be evaluated by Toka.
XSLT
<!-- Comment syntax is borrowed from XML and HTML. -->