[Help] Help me check my comments

This is a discussion on [Help] Help me check my comments within the C Programming forums, part of the General Programming Boards category; I've written a program but I don't know whether my comments are correct, suitable or missing. Please help me to ...

  1. #1
    Registered User
    Join Date
    Oct 2009
    Posts
    26

    [Help] Help me check my comments

    I've written a program but I don't know whether my comments are correct, suitable or missing. Please help me to check , I've put the "??" because I'm not sure about it.

    This is my code

    Code:
    #include <stdio.h>
    
    /* function main begins program execution */ 
    int main ()
    
    {
    	int i, j, tmp; /* initialize integers */
    	int num[10] = {5,6,3,2,8,9,0,4,1,7}; /* 10 unsorted arrays */
    
    	for (i = 1; i < 10; i++) /* number of loops */
    	{
    	for ( j = 0; j < 10; j++) /* ?? */
    		if (num[j] > num[j+1]) /* ?? */
    		{
    			tmp = num[j]; /* bubble sort formula */
    			num[j] = num[j+1];
    			num[j+1] = tmp;
    		}
    		printf("loop %d", i); /* prints loop */
    		for (j = 0; j < 10; j++) /* total numbers in a loop */
    			printf("%4d", num[j]); /* prints distance between numbers */
    		printf("\n"); /* begin new output line */
    	} /* end outer for */
    } /* end function main */
    Last edited by exjames1991; 10-15-2009 at 03:08 AM.

  2. #2
    Registered User
    Join Date
    Oct 2009
    Location
    While(1)
    Posts
    377
    Code:
    #include <stdio.h>
    
    /* function main begins program execution */ 
    int main ()
    
    {
            // Variable Declaration
    	int i, j, tmp; 
            
            // Declaring and initializing an unsorted array of integers
    	int num[10] = {5,6,3,2,8,9,0,4,1,7}; 
    
    	for (i = 1; i < 10; i++)
    	{
    	for ( j = 0; j < 10; j++) 
    		if (num[j] > num[j+1]) 
    		{
    			tmp = num[j]; 
    			num[j] = num[j+1];
    			num[j+1] = tmp;
    		}
    		printf("loop %d", i); 
    		for (j = 0; j < 10; j++) 
    			printf("%4d", num[j]); 
    		printf("\n");
    	} 	// end of for (i = 1; i < 10; i++)
    }

    First of all i want to say that u don't have to comment each and every line of code
    comment is necessary where u think logic is complex and by reading simple words
    any body can pick up the logic......

  3. #3
    and the Hat of Guessing tabstop's Avatar
    Join Date
    Nov 2007
    Posts
    14,185
    Quote Originally Posted by exjames1991 View Post
    I've written a program but I don't know whether my comments are correct, suitable or missing. Please help me to check , I've put the "??" because I'm not sure about it.

    This is my code

    Code:
    #include <stdio.h>
    
    /* function main begins program execution */ 
    int main ()
    
    {
    	int i, j, tmp; /* initialize integers */ /*This is incorrect, as these integers are uninitialized*/
    	int num[10] = {5,6,3,2,8,9,0,4,1,7}; /* 10 unsorted arrays */  /*This is incorrect, as this is one array of 10 numbers */
    
    	for (i = 1; i < 10; i++) /* number of loops */
    	{
    	for ( j = 0; j < 10; j++) /* ?? */
    		if (num[j] > num[j+1]) /* ?? */  /*If you don't know what > means, you're in a lot of trouble */
    		{
    			tmp = num[j]; /* bubble sort formula */  /*There is not and cannot be a "bubble sort formula" */
    			num[j] = num[j+1];
    			num[j+1] = tmp;  /*If you needed a comment at all for these three lines, it would be "swap num[j] and num[j+1]" */
    		}
    		printf("loop %d", i); /* prints loop */
    		for (j = 0; j < 10; j++) /* total numbers in a loop */
    			printf("%4d", num[j]); /* prints distance between numbers */  /*This is so amazingly incorrect */
    		printf("\n"); /* begin new output line */
    	} /* end outer for */
    } /* end function main */  /*You should never comment "end of <whatever>"; that's what indentation is for */
    My comments in red. Also agree with "way too many comments".

  4. #4
    Registered User
    Join Date
    Sep 2006
    Posts
    8,868
    Quote Originally Posted by exjames1991 View Post
    I've written a program but I don't know whether my comments are correct, suitable or missing. Please help me to check , I've put the "??" because I'm not sure about it.

    This is my code

    Code:
    #include <stdio.h>
    
    /* function main begins program execution */ 
    int main ()
    
    {
    	int i, j, tmp; /* initialize integers */  //remove
    	int num[10] = {5,6,3,2,8,9,0,4,1,7}; /* 10 unsorted arrays */ //1 unsorted array.
    
    	for (i = 0; i < 9; i++) /* number of loops */ //starting bubble sort change range from 0 to 9. i is the "lower" variable. j is the 'upper" variable.
    	{
            /* your sort is comparing num[j] with num[j+1]. When j == 9, j+1 is outside the array. Your comparison should be num[i] with num[j].
    	for ( j = 1; j < 10; j++) /* ?? */ //you need baces added to this for loop
    		if (num[j] > num[j+1]) /* ?? */ //if num[i] > num[j]
    		{
    			tmp = num[j]; /* bubble sort formula */ //swap
    			num[j] = num[j+1];  //num[j] = num[i]
    			num[j+1] = tmp;      //num[i] = tmp;
    		}
    		printf("loop %d", i); /* prints loop */ //remove comment
    		for (j = 0; j < 10; j++) /* total numbers in a loop */ //remove comment
    			printf("%4d", num[j]); /* prints distance between numbers *///should be num[j] - num[i] or some subtraction going on here
    		printf("\n"); /* begin new output line */ //remove obvious comment
    	} /* end outer for */
    } /* end function main */
    Lines of code that are totally self explanatory, need no comment. Comment a few to guide a new reader, into what the code is doing, and how. That, and anything odd, that wouldn't be clear at first look, when seen by another programmer.

    That is all the comments you need, or want.

    I find adding ending loop comments helpful like: "end of outer for... whenever the loop is large enough that I can't see the whole loop, on the screen, at one time.
    Last edited by Adak; 10-15-2009 at 08:10 AM.

  5. #5
    Jack of many languages Dino's Avatar
    Join Date
    Nov 2007
    Location
    Katy, Texas
    Posts
    2,309
    In professional code, comments will tend to be aligned vertically where it makes sense.

    When adding comments, you are adding them for yourself and others, but more importantly for others, so direct your comments to the others who will follow and who will be trying to fix, enhance, or perhaps even grade your work.
    Mac and Windows cross platform programmer. Ruby lover.

    Quote of the Day
    12/20: Mario F.:I never was, am not, and never will be, one to shut up in the face of something I think is fundamentally wrong.

    Amen brother!

  6. #6
    Registered User
    Join Date
    Oct 2009
    Posts
    26
    Thx alot guys, now I'm more clear and understand to how bubble sort works.

  7. #7
    Algorithm Dissector iMalc's Avatar
    Join Date
    Dec 2005
    Location
    New Zealand
    Posts
    6,304
    The most important thing when commenting code in the real world is not to say what the code is doing, but to say why it is doing it!
    The worst thing you can do is something like this:
    Code:
    i++; // increment i
    The only kind of person that would help would be one who doesn't know the C language and does know the meaning of increment. In reality, such a person will probably not be having any contact with your code, ever.

    Having said that, commenting for an assignment is sometimes slightly different from real-world commenting because it can help to show that you understand what is going on. Just don't do too much of that. It is just as easy to over comment as it is to have too few comments.

    Next point: You are overrunning your buffer. j goes from 1 to 9, and your if statement accesses item [j+1] That's item 10 in an array that only has valid indexes of 0 to 9 (arrays start at zero).
    My homepage
    Advice: Take only as directed - If symptoms persist, please see your debugger

    Linus Torvalds: "But it clearly is the only right way. The fact that everybody else does it some other way only means that they are wrong"

  8. #8
    Registered User
    Join Date
    Oct 2009
    Posts
    26
    As to my understanding,

    Code:
    	tmp = num[j]; /* swap */
    	num[j] = num[j+1]; /* num[j] = num[i] */
    	num[j+1] = tmp; /* num[i] = tmp */
    It says that num[j]=num[j] and num[j+1]=num[i] but how come in the code below says that num[j]=num[i].

    Code:
    if (num[j] > num[j+1]) /* if num[i] > num[j] */
    And for this

    Code:
    printf("%4d", num[j]); /* num[j] - num[i] */
    Why is num[j]-num[i]? What are J and I differences and what are them?
    Please help me to clarify.

  9. #9
    and the Hat of Guessing tabstop's Avatar
    Join Date
    Nov 2007
    Posts
    14,185
    Quote Originally Posted by exjames1991 View Post
    As to my understanding,

    Code:
    	tmp = num[j]; /* swap */
    	num[j] = num[j+1]; /* num[j] = num[i] */
    	num[j+1] = tmp; /* num[i] = tmp */
    It says that num[j]=num[j] and num[j+1]=num[i] but how come in the code below says that num[j]=num[i].

    Code:
    if (num[j] > num[j+1]) /* if num[i] > num[j] */
    I'm thinking that's just where Adak forgot how bubble sort works. (You should be having j and j+1 like you do, just keeping j in bounds (0 through 8 instead of 1 through 10.)
    Quote Originally Posted by exjames1991 View Post
    And for this

    Code:
    printf("%4d", num[j]); /* num[j] - num[i] */
    Why is num[j]-num[i]? What are J and I differences and what are them?
    Please help me to clarify.
    There he changed your code to match your comments -- your comment said you were printing the differences, so he changed your code to print the difference.

  10. #10
    Registered User
    Join Date
    Oct 2009
    Posts
    26
    Moderators, please close and lock this thread so prevent any illegal act or abuse. Thank you

  11. #11
    Registered User
    Join Date
    Oct 2009
    Posts
    26
    10 letters long **** **** ****

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. BN_CLICKED, change button style
    By bennyandthejets in forum Windows Programming
    Replies: 13
    Last Post: 07-05-2010, 11:42 PM
  2. Please check this loop
    By Daesom in forum C++ Programming
    Replies: 13
    Last Post: 11-02-2006, 12:52 AM
  3. Check application visibility
    By 3saul in forum Linux Programming
    Replies: 2
    Last Post: 02-13-2006, 04:13 PM
  4. comment on my comments
    By anthonye in forum C Programming
    Replies: 8
    Last Post: 02-01-2002, 10:31 AM
  5. check my code ( if statement, file existance )
    By Shadow in forum C Programming
    Replies: 1
    Last Post: 10-04-2001, 11:13 AM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21