Wednesday, January 4, 2012

How do we write valuable comments?

Be wise in your use of comments. Remember that comments are used to enhance the understandability of your programs. Make them pleasing to the eye and clear. With practice, you will develop a style of writing comments that is of benefit to you. I do not use many comments, primarily because I want you to interpret the code yourself. Your programs should use comments far more frequently than I use them.
I recommend that you avoid writing comments on the same line as other C code unless you can clearly distinguish the comments from the code. It often looks much better if your comments are on lines separate from other statements. There is no standard for writing comments, but I like a style that highlights comments and separates them from other C text. The reason for this is that, if not highlighted, comments tend to blend in with the rest of the code and make following the logic of the code confusing. In other words, do not hide your comments. Make them stand out- they are there to help you and others. I like a style in which each comment line begins with two stars, and the comment block begins and ends with a line of stars. For instance, I strongly recommend that you add a banner at the beginning of your programs. A banner is a set of comments that describe such things as the name, parameters used, history, author, purpose, and date of the program. A better look would be as follows:

/*********************************************************************
** Name: Hola.C
** Purpose: Learning how to write comments in C
** Date: Written on 1/4/12
** Author: 3nriched
** Reference: None
*********************************************************************/

#include

int main(void)
{
printf("How do we write comments in C?");
}


No comments:

Post a Comment