C Tutorial (3) : Comments in C code

Your computer must be able to understand your programs. Because the computer is a dumb machine, you must be careful to spell C commands exactly right and type them in the order you want them executed.

However, people also read your programs. You will change your programs often, and if you write programs for a company, the company’s needs will change over time. You must ensure that your programs are understandable to people as well as to computers. Therefore, you should document your programs by explaining what they do.

Commenting on Your Code

Throughout a C program, you should add comments. Comments are messages scattered throughout your programs that explain what’s going on.

  • If you write the program and only you will use it, you don’t really need comments, right? Well, not exactly. C is a cryptic programming language. Even if you write the program, you aren’t always able to follow it later—you might forget why you wrote a particular chunk of code, so a comment will help to decipher matters.
  • Add comments as you write your programs. Get in the habit now, because
    programmers rarely go back and add comments later. When they must make a change later, programmers often lament about their program’s lack of comments.
  • Another advantage is gained when commenting as you write the program instead of waiting until after you finish is: while writing programs, you often refer back to statements you wrote earlier in the process. Instead of reinterpreting C code you’ve already written, you can scan through your comments, finding sections of code that you need faster. If you didn’t comment, you would have to decipher your C code every time you looked through a piece of it.

Program maintenance is the process of changing a program over time to fix hidden bugs and to adapt the program to a changing environment.

Comments are not C commands. C ignores every comment in your program. Comments are for people, and the programming statements residing outside the comments are for the computer.
Consider the following C statement:

return ((s1 < s2) ? s1 : s2);

You don’t know C yet, but even if you did, this statement takes some study to figure out. Isn’t this better?

return ((s1 < s2) ? s1 : s2); /* Gets the smaller of two values */

The next section explains the syntax of comments, but for now, you can see that the message between the /* and the */ is a comment.

Don’t write a comment just for the sake of commenting. The following statement’s
comment is useless:

printf("Payroll"); /* Prints the word "Payroll" */

Add comments to explain what is going on to people (including yourself) who might need to read your program.

Syntax

C comments begin with /* and end with */. Comments can span several lines in a program, and they can go just about anywhere in a program.

/* This is a comment that happens to span two lines
before coming to an end */
/* This is a single-line comment */
for (i = 0; i < 25; i++) /* Counts from 0 to 25 */

Notice that comments can go on lines by themselves or before or after programming statements. The choice of placement depends on the length of the comment and the amount of code the comment describes.

Don’t comment every line. Usually only every few lines need comments. Many programmers like to place a multiline comment before a section of code and then insert a few smaller comments on lines that need them.

Many companies require that their programmers embed their own names in comments at the top of programs they write. If changes need to be made to the program later, the original programmer can be found to help.

It’s also a good idea to include the filename that you use to save the program on disk at the beginning of a program so that you can find a program on disk when you run across a printed listing.

/***************************************************************
 * File name : ji_sample_c_code.c
 * Author : ji.anukulverma@gmail.com
 * Date created : 11/01/2017
 * ------------------------------------------------------------
 * Description : Sample code for C tutorial
 ***************************************************************
 * Copyright (C) 2017 Creative Ji
 * All rights reserved.
 ***************************************************************/

main()
{
  ......
}

For testing purposes, you might find it useful to comment out a section of code by
putting /* and */ around it. By doing this, you cause C to ignore that section of code,
and you can concentrate on the piece of code you’re working on. Do not, however,
comment out a section of code that already contains comments because you cannot
embed one comment within another. The first */ that C runs across triggers the end of the comment you started. When C finds the next */ without a beginning /*, you get an error.

A Second Style for Your Comments

For single-line comments, you can also use //.

Today’s C compilers support another kind of comment that was originally developed for C++ programs. With its C99 release, the American National Standards Institute (ANSI) committee approved this new kind of comment, so you should be safe using it (unless you are using a really, really old computer and compiler!). The second style of comment begins with two slashes (//) and ends only at the end of the line.
Here is an example of the new style of comment:

// Another Code Example, just with a different commenting style
#include <stdio.h>
main()
{
  printf("I like these new comments!"); // A simple statement
}

WhiteSpace

Whitespace is the collection of spaces and blank lines you find in many programs. In a way, whitespace is more important than comments in making your programs readable. People need whitespace when looking through a C program because those programs are more readable than programs that run together too much. Consider the following program:

#include <stdio.h>
main(){float a, b;printf("How much of a bonus did you get? ");scanf(" %f", &a);
b = .85 * a;printf("If you give 15 percent to charity, you will still have
%.2f.", b);return 0;}

To a C compiler, this is a perfectly good C program. You might get a headache looking at it, however.
Although the code is simple and it doesn’t take a lot of effort to figure out what is going on, the following program is much easier to decipher, even though it has no comments:

#include <stdio.h>
main()
{
  float a, b;
  printf("How much of a bonus did you get? ");
  scanf(" %f", &a);
  b = .85 * a;
  printf("If you give 15 percent to charity, you will still ");
  printf("have %.2f.", b);
  return 0;
}

This program listing is identical to the previous program, except that this one includes whitespace and line breaks. The physical length of a program does not determine readability; the amount of whitespace does. (Of course, a few comments would improve this program, too, but the purpose of this exercise is to show you the difference between no whitespace and good whitespace.)

Your first C Program < Prev                                                                                   Next > Printf

Advertisements

2 comments

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s