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

Siblings Pete and Alexa Ingram-Cauchi Talk iD Tech and Tech Summer Camps

They talk about how they started and run iDTech summer camps together and how parents can evaluate tech summer camps.

Where to Recycle Electronics

Here are a few places where you can recycle your old electronics safely.

What is a High Level Language?

What are the differences between high level languages and machine languages? And how do these differences impact coding?

An Interview with Boone Gorges

Learn how a humanities PhD became a software programmer who builds online communities for universities, as well as Lead Developer for BuddyPress and helping to create WordPress plugins like Anthologize and Participad.

How to Make (and Keep) New Years Resolutions

A few great ideas on how to make New Year's resolution you might actually keep, and have fun doing so. Whether you like structure or hate it, here are a few approaches and a number of resources to help.

News Wire Stories for December/January

Interesting stories about computer science, software programming, and technology for the month of November 2013.

No computer has ever been designed that is ever aware of what it’s doing; but most of the time, we aren’t either.

The Hungry Camel

How many measures of grain can one camel eat while delivering grain, before the camel runs out of grain to deliver? A fun math problem at least 1,000 years old.

How to Do Online Research

Online research skills are critical for software programmers. It's how you learn any language, by searching for error messages and looking up reference material.

Comments

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

Take Out the Garbage

In the same way your bedroom may be impossible to enter if you let dirty clothes pile up, computers can crash and refuse to operate if their memory is stuffed with unused data.

bin, boot, opt, and Linux File System Hierarchy Mysteries

The Linux directory structure looks confusing compared to Windows. Here are the names and purpose of each directory.

What is Localhost?

Localhost is available on most computers, usually to display web pages. It's also useful to use to learn coding on your computer.

The Paywall and Adding Voices to Help Kids Code

With this issue, you will find some articles require subscription. Here's an explanation and how you can help add writers and voices to future issues of this magazine.

Learn More Links for December 2013/January 2014

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