A general note about comments

Many programming tutorials never mention comments or leave them to the very end as an afterthought. The people who wrote those tutorials never worked in a support role.

Trying to sort out a problem on a program that you have not looked at for several months (or if you have inherited it, never) can be very difficult. This task can be made very much easier if there are good quality comments in the program.

As well using good comments, code that is laid out so that it is easy to understand is a form of etiquette. You are acknowledging that others may want to read and understand what you have written. Of course, if you are ashamed of your own code then even good comments and layout won't help.

Over the years I have developed my own style that is neat, clean and applicable to many different programming languages. It may look strange or fussy in some or even all languages but it ensures that I can move between languages with little effort.

Of course, occasionally some people go overboard and write their life history in the comments to their code. While this is probably better than no comments at all, it can make for a lot of reading that would be better placed in a separate document. What is worse is that sometimes they are actually misleading and can cause great confusion.

Strange as it seems, it is better to have a program with no comments than one that has misleading comments. You can waste a lot of time before you realise that the comments are wrong and you need to look it it all again.

So use comments, but use them wisely. If you copy the comments from somewhere else make sure that they are correct for the new location. If you change the parameters for a function, then make sure that the comments do not still describe the old parameters.

Most importantly, go back and read your own comments from time to time and see if they still make sense.

Single Line Comments

A single line or part of a line can be commented by starting the comment with two slashes (//). Everything after the slashes is ignored.

//This a single line comment
put "Hello World"    //This is a comment at the end of a line.

Multiple Line Comments

Using the multi-line comment syntax a comment can be anything from a part of a line to many lines.

Multi-line comments start with (/*) and end with (*/) and can span many lines. Anything in between is ignored. They can also be nested so that a comment can be wholly enclosed within another comment.

put /*this is a comment*/ "Hello World"

put "Hello World" /* This comment goes over 
                     two lines */
/* This comment spans several lines ...
put /*this is a comment*/ "Hello World"
//This a single line comment
... and includes two other comments */

Automatic Documentation

Some automatic documentation programs, such as Doxygen, require comments to be in a specific format.

Looking through some programs, the layout of the comments can look strange until you understand the program that is being used to create the external documentation. Each program can have slightly different requirements.

programmers_guide/comments.txt · Last modified: 2015/01/06 09:06 by don