Comment (computer programming)

In computer programming, a comment is text embedded in source code that a translator (compiler or interpreter) ignores.

[2] Some development tools, other than a source code translator, do parse comments to provide capabilities such as API document generation, static analysis, and version control integration.

The flexibility supported by comments allows for a wide degree of content style variability.

[7] Comments can also be classified as either prologue or inline based on their position and content relative to program code.

Comments may explain why a choice was made to write code that is counter to convention or best practice.

This might apply for highly specialized problem domains or rarely used optimizations, constructs or function-calls.

By systematically commenting out and running parts of the program, the offending source code can be located.

Many IDEs support adding and removing comments with convenient user interface such as a keyboard shortcut.

Common metadata includes the name of the original author and subsequent maintainers, dates when first written and modified, link to development and user documentation, and legal information such as copyright and software license.

Many support reading information from comments, often parsing metadata, to control the content and formatting of the resulting document.

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

Such syntax may be a practical way to maintain compatibility while adding additional functionality, but some regard such a solution as a kludge.

If an explicit indication of fall-thru is not found, then the compiler issues a warning about a possible coding problem.

Inserting such a comment about fall-thru is a long standing convention, and the compiler has codified the practice.

[23] For example: To relieve stress or attempt humor, sometimes programmers add comments about the quality of the code, tools, competitors, employers, working conditions, or other arguably unprofessional topics – sometimes using profanity.

[24][25] There are various normative views and long-standing opinions regarding the proper use of comments in source code.

[26][27] Some of these are informal and based on personal preference, while others are published or promulgated as formal guidelines for a particular community.

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

For example, the following Java comment would be suitable in an introductory text designed to teach beginning programming: This level of detail, however, would not be appropriate in the context of production code, or other situations involving experienced developers.

For example, in this Perl: If a language supports both line and block comments, programming teams may decide upon a convention of when to use which.

Programmers often use one of select words – also known as tags, codetags[37][38] and tokens[39] – to categorize the information in a comment.

Commonly used tags include: For example: Syntax for comments varies by programming language.

Notable languages include: Bash, Raku, Ruby, Perl, PowerShell, Python and R. An example in R: A block comment is delimited by =begin and =end that start a line.

For example: Instead of a regular block commenting construct, Perl uses literate programming plain old documentation (POD) markup.

Notable languages include: Ada, Eiffel, Haskell, Lua, SQL and VHDL.

For example: Haskell also provides a literate programming method of commenting known as "Bird Style".

One additional requirement is a blank line before and after the code block: Literate programming can also be accomplished via LaTeX.

For example: Early versions of BASIC used REM (short for remark) for a line comment.

[52][53] It is possible to insert human-readable content that is actually part of the configuration, and may be saved to the NVRAM startup-config via: The following Fortran IV code fragment shows that comment syntax is column-oriented.

[55] In Niklaus Wirth's more modern family of languages (including Modula-2 and Oberon), comments are delimited by (* and *).