This Code Snippets section of the magazine explains parts of programming languages common across most or all languages. It's a great way to understand how languages work. And it helps reduce the ability of a new programming language to glaze your eyes. Learning how to code should be much easier and less frightening if I explain a part of a programming language, then show you how it works in a couple different languages.

Let's get started by talking about comments.

Comments can be defined by one or more of these properties:

• Whether they are inline, often to the immediate right of a line of code, or a single line or block of comments above one or more lines of code.
• Whether or not comments can be nested one comment inside another.
• The purpose of a comment, whether a docstring used to generate documentation for the code or a quick note to orient coders.

Many languages either use or accept the comment notation used by C, C++, and Perl. However, there are differences both interesting and worth discussion.

For example, one of the first programming languages, Fortran, indicated comments with a capital C in column 1 of any line of code. Visual Basic uses a single quote ( "˜ ) at the start of a comment. Meanwhile, a number of languages uses double forward slashes ( // ), others uses a double dash ( — ), while still other languages use the pound sign ( # ).

Let's look at how comments are implemented in a few languages.

Python

PEP 8 Style Guide for Python Code includes a section on how to style and organize comments used in Python code. This PEP dates back to July 2001. PEP 257 covers docstrings, bits of comments to be used in documentation for the code, especially code used by the public. And, if you don't know, PEP is short for Python Enhancement Proposal, a design document and often technical specification the Python community uses to collect community input and support then document their agreements.

Here's a basic example of inline comment notation in Python, with at least two spaces between the code and the # symbol plus a space then the short comment:

headtag = "<h2>"  # start by opening head tag

However, inline comments are discouraged in Python for clarity. Too many comments clutter the code. Here's an example of a comment in Python for a block of code:

#
build the heading by adding the
HTML tag to the title variable
#
headtag = "<h2>" + title + "</h2>"

Blocks of comments in Python must use the same indent level as the code they document. This helps match comments with blocks of code. It's also in PEP 8 as the community-agreed upon style for block comments.

PHP

The PHP language supports the comment style used for C, C++, and Perl. Single line and inline comments use this notation:

<?php
// This code does something
color = "blue";
?>

<?php
$color = "blue";  // assign the color
$text   = "The house is " . $color;  # The pound symbol also works to mark comments
?>

Multi-line comments in PHP use this notation:

/* This is a first line comment.
   This is a second line comment. */

Multi-line comments end at the first instance of */ so nesting comments doesn't work easily and is discouraged. In short, it's important to use comments well but sparingly, ensure they're clearly marked and, wherever possible, on their own lines apart from code.

Lua

In the Lua language, comments begin with a double hyphen, like this:

-- a basic Lua statement
print "Hello World!"

Multi-line comments use a double hypen followed by a square bracket followed by a parentheses, like this:

--[[
This is first comment line.
This is second comment line.
--]]

The open and close comment tags are set on individual lines here only to help with readability. The double-dash tells Lua this is a comment and the double brackets mark the start and end of a multi-line comment.

Haskell

With Haskell, comments use a combination of curly brackets and a single hyphen:

{- this is a comment in Haskell -}

Comments can be nested in Haskell, as well. Multi-line comments use the same notation:

{-
This is line one of a comment.
This is line two of a comment.
-}

Learn More

Haskell

http://www.haskell.org/haskellwiki/Reference_card#Comments

Lua

http://en.wikibooks.org/wiki/Lua_Programming/How_to_Lua/comment
http://www.lua.org/pil/1.3.html

PHP

http://php.net/manual/en/language.basic-syntax.comments.php

Python

http://www.python.org/dev/peps/pep-0008/#comments

Comments in Programming Languages

http://www.gavilan.edu/csis/languages/comments.html

Comparison of Programming Language Syntax

http://en.wikipedia.org/wiki/Comparison_of_programming_languages_%28syntax%29#Comments