Skip to content

including code comments

Protologism ahead

This is a protologistic compound word I have created out of the following need:

  • In my experience, a comment in the context of writing computer instructions is not just a programmer-readable explanation or annotation and can be found in more places than just the source code of a computer program.

It is based on Wikipedia's definition of comment (computer programming):

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters.1 2

Code refers to any kind of computer instructions written in a computer language, and is based on one of Wiktionary's definitions of code:

(programming, uncountable). Instructions for a computer, written in a programming language; the input of a translator, an interpreter or a browser, namely: source code, machine code, bytecode.

Source code refers to any set of computer instructions before they are carried out, including HTML3.

A code comment is any textual material relevant to and included with computer instructions that is intended to be omitted or hidden when those instructions are carried out.

CSS code comments

Use /* foobar */, where foobar is the code comment. The strings /* and */ surround one or more lines of text to make a code comment. CSS code comments may not be nested4, and it is not valid CSS to indicate a comment with only the string // at the beginning of a line5.

HTML code comments

Use <!-- foobar -->, where foobar is the code comment. The strings <!-- and --> surround one or more lines of text to make a code comment. HTML code comments are ignored by the browser and are usually invisible to the user, but they can be viewed in Firefox or Google Chrome using the view source tool.

Markdown code comments

Markdown has no official syntax for code comments, but implementations that support raw HTML can use HTML code comments, instead.

Hack to omit code comments when carrying out computer instructions

If you want a comment that is strictly for yourself (readers of the converted document should not be able to see it, even with "view source") you could (ab)use the link labels (for use with reference style links) that are available in the core Markdown specification:

http://daringfireball.net/projects/markdown/syntax#link

That is:

[comment]: <> (This is a comment, it will not be included)
[comment]: <> (in the output file unless you use it in)
[comment]: <> (a reference style link.)

Or you could go further:

[//]: <> (This is also a comment.)

To improve platform compatibility (and to save one keystroke) it is also possible to use # (which is a legitimate hyperlink target) instead of <>:

[//]: # (This may be the most platform independent comment)

For maximum portability it is important to insert a blank line before and after this type of comment, because some Markdown parsers do not work correctly when definitions brush up against regular text. The most recent research with Babelmark shows that blank lines before and after are both important. Some parsers will output the comment if there is no blank line before, and some parsers will exclude the following line if there is no blank line after.

In general, this approach should work with most Markdown parsers, since it's part of the core specification. (even if the behavior when multiple links are defined, or when a link is defined but never used, is not strictly specified).

YAML code comments

Use # foobar, where foobar is the code comment. The number sign character (#) makes a code comment out of the text between it and the end of the line, and can start anywhere on a line. YAML code comments must be separated from other tokens by white space characters.6 Number signs that appear inside of a string are number sign literals.

formats lacking support for code comments

licensing

Some rights reserved: CC BY-SA 3.0. Includes significant content from:

prior work

  1. 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, plese start120--121. ISBN 981-238-426-X. ↩

  2. 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. ↩

  3. https://support.google.com/surveys/answer/6172725?hl=en ↩

  4. https://www.w3.org/TR/CSS21/syndata.html#comments ↩

  5. https://stackoverflow.com/questions/11218808/do-double-forward-slashes-direct-ie-to-use-specific-css/11218889#11218889 ↩

  6. "YAML Ain't Markup Language (YAML™) Version 1.2". Yaml.org. Retrieved 27 May 2015. ↩