That's not something I can really answer. There are no hard and fast rules.
Comments are used to annotate your code. They're there to aid someone who is totally unfamiliar with your program, and maybe totally unfamiliar with programming and C as well, read through it.
So if it makes sense to put a simple comment that says:
When you have several printf's and scanf's that work to that effect, then having the comment is better than not. This way, they only need to read the comment to understand the next several lines of code without having to actually read each printf/scanf -- and have to Figure It Out.
Comments should be used wherever the reader would have to
Think of it as a formatting issue. Would you find a book without a cover, or a header for each chapter?
See also the sections on: locations, variables, and functions.
Think of it as a formatting issue. Books have margins, a tab indicates a new paragraph. A new page indicates a new chapter. Chapter headers have a number centered at the top of the page and a blank line separates the number from the text. All of these sorts of issues should be considered when thinking about where to put a comment.
Comments should go where they don't conflict VISUALLY with your code. Comments are there to make the code easier to read. Not Harder. They can go between lines of code or at the end of a line. Wherever it makes sense (visually and conceptually) to put them.
Experiment. See how your code looks best.
Remember comments are there to aid understanding, not muddy it up.
See also the sections on: when, variables, and functions.
Yes.
No one should have to read your code to understand your program. Someone totally unfamiliar with programming -- someone who knows nothing about C -- should be able to pick up your program and understand what's supposed to happen.
See also the sections on: when, where, variables, and functions.
No. You need comments anywhere you think your program needs explanation according to the general guidelines set forth in this document.
Be sure you understand the sections on: when, where, variables, and functions.
Comments don't work that way. There's no rule that says: for every five lines of code you should have a two-line comment. Put them wherever they help make your code more readable.
For Example:
If it makes sense to put a simple comment that says:
This way, someone reading your program only needs to read the comment to understand the next several lines of code without having to actually read each printf/scanf -- and have to Figure Out What's Supposed To Happen.
See also the sections on: when, where, variables, and functions.
People familiar with C know what printf and scanf do. You don't need a comment for each call to printf and each call to scanf. But it might be a good idea to put a comment before a sequence of printf/scanf statements.
See also the sections on: when, where, variables, and functions.
GREAT!
And -- YES!
You can't totally remove the need for comments by having
significant variable names, but you can reduce the need for having
as many comments in your code. Significant variable names are an
essential part of good programming style. So are comments.
See also the sections on: when, where, and functions.
The comments that functions require should specify three things about
using the function correctly:
This is how I write comments regarding functions:
For Example: A function that takes 2 parameters and prints a 2d array.
I put these comments with the function prototype. I put a second copy with the function definition for recollection and clarity.
Other people write them other ways. Many people ask that comments regarding a function indicate pre-conditions and post-conditions that indicate the state of the program before the function and the state after the function is executed.
See also the sections on: when, where, and variables
There isn't one. Using comments is a style issue. Just as hard as it is to decide what to do with your braces and your spacing, it can be just as frustrating to decide how to most effectively use comments.
If you use too much space and put comments on lines by themselves, you can wind up with very long functions/subroutines that get very long, vertically. And you can't see as much of it on the screen at one time.
On the other hand, putting comments on lines by themselves makes your program very clear to read.
Do your best and think of comments the same way you think of roducing a good poster or presentation. It should be visually clear to understand.
graphics images Copyright 1998-2003 Elizabeth Fraley HTML code copyright 1998-2003 Elizabeth Fraley. Permission is given to provide these pages in their original, unaltered form online for educational purposes. They may not be republished or included on a CDROM, disk or other media or with any published work without the express permission of the copyright holder (this includes FAQ books).