C: Comments on source code

Got it! This site uses cookies. You consent to this by clicking on "Got it!" or by continuing to use this website.nbsp; Note: This appears on each machine/browser from which this site is accessed.

Most programming languages have ways of including comments in the source text file.

A program comment is text that is for the human reader or another program.

Comments in source code text have two primary uses.

Documentation for the human reader.
Hints to other programs (compiler, documentation systems, etc.).

Most programming languages support single line comments and many support multi-line comments.

Languages as C, C++, Java, JavaScript, and others (but not all languages) use the same comment convention.

// This is a single-line comment /* This is a multi-line comment */

Some languages, such as Python, have only single-line comments.

# This is a single line Python comment.

A comment in a BASH script, such as ~/.bashrc starts with a hash sign "#" and continues until the end of the line.

# This is a single line BASH comment.

Example from the ~/.bashrc file.

Used:

source ~/RMS/rmsInit.bsh

Ignored:

# source ~/RMS/rmsInit.bsh

HTML multi-line comments start with .

Some style rules for comments are now presented (for this class). If your company (or another class) has different style rules, go with the company (or other class) style rules for that company (or other class). Here are some style guidelines for comments.

Single line comments should be on a separate line, not after code.
The "/*" and "*/" for multi-line comments should be on separate lines.

Bad:

date1 = ... complex calculation ... ; // use ... to determine date

Good: (if comment is actually needed)

// use ... to determine date date1 = ... complex calculation ... ;

One will see two major issues with comment usage in source code.

Too many comments
Not enough comments

Some general rules for comment usage are now covered. Assume that the reader understands the programming language you are using, but point out any special tricks you are using that might not be obvious.

Bad comment:

// add 1 to x x = x + 1;

Any programmer knows that the statement adds 1 to x so it is unnecessary and a bad comment. Assume that the reader understands the background of the problem that you are solving. Do not repeat every little detail of the problem description. Instead, use comments to tie together the problem being solved with the way the code implementation is solving that problem.

Many style guidelines will require certain header comments in your program, such as the following.

/// File: ... /// Purpose: ... /// Author: (your name) /// Help received: // (add here) /// Pseudocode: // (add here)

These standardized comments help both the reader and a program that may be looking at the code. Here is another example.

///:BEGIN ToDo ///:END ToDo

A program can look at the code written between these two comments for specific analysis purposes.

In this case, the three slashes are used to indicate special comments to be used by other programs that inspect this program.

Avoid visual noise in your program.

Bad: (use asterisks)

// ************************************* // Routine to do something important // *************************************

Good: (use white space)

// Routine to do something important