beanz Magazine

Comments

geishaboy500 on Flickr

Almost all programming languages include the ability to add comments and other notes in your code. Here's how several languages work with comments.

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

Also In The December 2013 Issue

An Interview with Troy Hunt

Troy Hunt is a software architect and Microsoft Most Valued Professional (MVP) focusing on security concepts and process improvement in a Fortune 50 company. He's based in Australia.

1Password, LastPass, RoboForm

If you use a password you created that is less than eight characters, your password is vulnerable to hacking. Here are three ways to create and use secure passwords online.

How to Write Secure Code

Coding securely doesn't have to kill the joy of programming. In fact, learning how to code securely provides insights into languages and computing.

How to Code HTML Email

How to code an HTML email like the ones you open every day turns out to be an offbeat software coding challenge.

What is an SSL Certificate?

How to tell if a web page is secure is one of the most basic yet least obvious ways to protect your data online.

Where to Find Command Line Interface Software

One key computing skill is the ability to use command line interface (CLI) software to enter commands to control a computer. Here are some options.

Lua

Lua is a comparatively simple programming language used in a wide range of places, from digital TVs to video games to phone applications. It's also designed to be simple to use and lightweight.

Arrays

Here is how three programming languages handle a common problem: how do you organize and keep track of useful data?

Linux Command List for Command Line Interfaces

Some of the most common commands you'll need for a command line interface (CLI), in a Linux command list.

Computer science education cannot make anybody an expert programmer any more than studying brushes and pigment can make somebody an expert painter.

News Wire Stories for October 2013

Must read stories about computer science, software programming, and technology for September 2013.

Learn More Links for October 2013

Links from the bottom of all the October 2013 articles, collected in one place for you to print, share, or bookmark.