Questions about commenting and why won't this program exit?

[Kjorin]

I wanted to post my latest program in its entirety to get feedback on my comments but code must contribute to the post character limit. Instead, I want to ask what is "the norm" for program commenting in the real world? What types of things generally merit comments? What makes a "good" comment?

Also, please look at this snippet of my tic-tac-toe program as it doesn't want to exit when I send the code back to main(); from game_over();.

bool first_run = true;

int main()
{
    if( first_run == true )
    {
        play_game();
    }
    else
        return 0;
}

void game_over( mark game_winner )
{
    int input = 0;
    cout << "Play again?" << endl;
    cout << "1) Yes" << endl;
    cout << "2) No" << endl << endl;
    cin >> input;

    switch( input )
    {
    case 1:
        // Irrelevant stuff...

    case 2:
        cout << endl;
        cout << "Thank you for playing!" << endl;

        first_run = false;
        main();
        break;
    }
}

[TheIdeasMan]

Hi,

Sorry to start with bad news, but don't ever call main(), in this case you just want the function to end naturally, control will return to main() by itself. This is how functions work, they either return a value or for void functions, they just end. So delete line 31.

I wanted to post my latest program in its entirety to get feedback on my comments but code must contribute to the post character limit. Instead, I want to ask what is "the norm" for program commenting in the real world? What types of things generally merit comments? What makes a "good" comment?

First of all, if one has really good names for the variables and functions, then the code itself becomes self documenting without any comments. Reading the code should be like reading a story. Here's a comical version of what I mean :+)

http://www.cplusplus.com/forum/lounge/176684/#msg872881

To achieve this, avoid abbreviating names, and by having variable names that look too similar. I am not fond of i and j in the same context - it can cause problems. Also name variables for what they are: E.g. Row and Column, not a and b, or i and j.

One can have single char names when if it's a mathematical context, if the formula from wiki or elsewhere uses variables a, b, c, d, then it's ok for your code to use them too. For example, this is probably fairly obvious: y = r * sin(theta);, but some might even argue for : YOrdinate = Radius * sin(theta); Code is easier to follow when it's the same form as the documentation it comes from.

Put comments in for web addresses of the documentation you are using - the wiki page for example, or any other web page which might be useful. I have put comments for the actual formula with all it's Greek characters and exponents in, just before the function that does that calculation, so it's clear to me, and to others.

Comments about what a function does, and it's expected range of valid values, and it's expected output (pre-conditions & post-conditions) are very useful - one should almost always do that. There is a utility call Doxygen which helps generate documentation about your code: it uses doxygen comments to do so.

Put comments if you have done something tricky or unusual.

Don't put comments for something that is obvious in the code.

Here is some other really good reading from Bjarne Stroustrup and Herb Sutter:

https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md

Good Luck !!

Edit:
If you have lots of code, try posting it over several posts. If you really have a lot, put it on a hosting service like PasteBIn or GitHub or many others.

[Kjorin]

Thank you for the excellent response.

Sorry to start with bad news, but don't ever call main()
Edit & Run
, in this case you just want the function to end naturally, control will return to main()
Edit & Run
by itself. This is how functions work, they either return a value or for void functions, they just end. So delete line 31.

I did think it was strange calling main() from inside another function because if I remember correctly main() doesn't take arguments like other functions. I must have confused myself by over thinking that the program would just stop doing anything (but not terminate) if it did not go back to main().

First of all, if one has really good names for the variables and functions, then the code itself becomes self documenting without any comments. Reading the code should be like reading a story.

This was very helpful as I try to give everything descriptive names so going back to add comments seemed redundant. I know that documentation is important when working with others and your future self so I wanted to make sure I had the right idea from the start instead of developing bad habits.

Edit:
If you have lots of code, try posting it over several posts. If you really have a lot, put it on a hosting service like PasteBIn or GitHub or many others.

I'm actually a little relieved I didn't get to post the entire program as I find the abundant use of if/else statements to check everything embarrassing, but hey, everyone has got to start somewhere.

[Kjorin]

I removed bool first_run() from the program but it is still not terminating, is it because of the infinite loop I used inside the play_game() function below?

int main()
{
    play_game();
}

void play_game()
{
    int input = 0;

    while( true )
    {
        draw_game_board();
        cout << endl;

        switch( player_number )
        {
        case 1:
            cout << "Player One (X's) choose a square: ";
            cin >> input;
            square_update( input );
            break;
        case 2:
            cout << "Player Two (O's) choose a square: ";
            cin >> input;
            square_update( input );
            break;
        }

        check_for_winner();
    }
}

void check_for_winner()
{
    // Horizontal win conditions
    if( (SQ_one == X && SQ_two == X && SQ_three == X) || (SQ_four == X && SQ_five == X && SQ_six == X) || (SQ_seven == X && SQ_eight == X && SQ_nine == X) )
    {
        cout << "Player One (X's) wins with a horizontal line!" << endl;
        game_over( X );
    }
    
    // More embarrassingly long if/else statements to check for a winner...

}

void game_over( mark game_winner )
{
    int input = 0;

    cout << "Play again?" << endl;
    cout << "1) Yes" << endl;
    cout << "2) No" << endl << endl;
    cin >> input;

    switch( input )
    {
    case 1:
        // Irrelevant stuff...
        break;
    case 2:
        cout << endl;
        cout << "Thank you for playing!" << endl;
        break;
    }
}

After choosing "No." in the game_over() function after winning as Player One (X's), the program seems to go back to the switch( input ) case: 2 in play_game(), printing the game board and asking Player Two (O's) to select a square.

[TheIdeasMan]

Hi,

Consider having a bool controlled while loop:

bool Quit = false;

while (!Quit) {
  // call function to show menu, include a quit option
  // get input for switch
  // switch
 // normal cases for switch, each one should call a function
  case 'Q' :  
      Quit = true;
  default:
    std::cout << "Bad Input";

}

Try to avoid infinite loops wherever you can.

Understand how values are passed between functions, at the moment all the functions are void, there are no references being used, so no information travels between functions.

Consider using arrays for a Tic-Tac-Toe game, rather than variables. There will be a lot of if statements.

Only check for a win after there have been 6 or more moves.

Google about Tic-Tac-Toe games, there are zillions of them.

Good Luck !!

[Kjorin]

I appreciate the advice and will bear it in mind. As for using an array, I haven't gotten that far in the book yet (the tic-tac-toe game is an end of chapter problem before the array chapter), but you are most certainly correct about there being a lot of if statements!

Thanks again for the excellent replies! :)