Just need a bit of advice

[FuryEnder]

I just need some advice on creating more useful comments, and perhaps improving the readability of the code itself. I don't expect you to painstakingly go through the 126 lines of code. Thanks in advance.

#include <iostream>
#include <string>		//declarations
#include <limits>
using namespace std;

char response;
char response2;
int response3;
string guess1;		//variable declarations
string guess2;
string guess3;

int lose();			//function prototypes
int win();

class Game3 {
public:
	void guessThree(){
		cout << "Alright, last one. 'neltat'";
		cin >> guess3;		//user input
		if (guess3 == "talent" || guess3 == "Talent") {		//correct input
			cout << "That is correct!\n";
			cout << "Wow, you're really, really good!\n";
			win();		//calls win function which is end of program
		}
		else {		//incorrect input
			cout << "No, sorry, that's not correct.\n";
			cout << "Exiting...\n";
			lose();		//calls lose function which is end of program
		}
	}
};

class Game2 {
public:
	void guessTwo(){
		cout << "Alright, let's continue. 'hnarcb'";
		cin >> guess2; // user input
		if (guess2 == "branch" || guess2 == "Branch") { //this is the correct input
			cout << "That is correct!\n";
			cout << "Wow, you're good!\n";
			Game3 guesscall3; // call class Game3
			guesscall3.guessThree();
		}
		else {		//incorrect input
			cout << "No, sorry, that's not correct.\n";
			cout << "Exiting...\n";
			lose(); // calls lose function
		}
	}
};


class Game1{
public:
	void guessOne(){ 
		cout << "Alright, let's begin. 'mfsfiun'";
		cin >> guess1; //user input
		if (guess1 == "muffins" || guess1 == "Muffins") {		//correct input
			cout << "That is correct!\n";
			cout << "Wow, you're good!\n";
			Game2 guesscall2; // call class Game2
			guesscall2.guessTwo();
		}
		else {  //incorrect input
			cout << "No, sorry, that's not correct.\n";
			cout << "Exiting...\n";
			lose(); // calls lose function
		}
	}
};


class Instructions {		//first class that is called
public:
	void playerInstructions(){
		cout << "Alright, I'll give you a scrambled-up word "
			<< "and you'll input the un-scrambled word.";
		cout << "For example, 'fdoo' would be food!\n";
		cout << "Do you still want to play?[Y/N]\n";
		cin >> response2;			//'Y' calls class Game1
		if (response2 == 'Y' || response2 == 'y') {
		cout << "Alrighty then!.\n";
		Game1 guesscall1;
		guesscall1.guessOne(); // call class Game1
	}
	else if (response2 == 'N' || response2 == 'n') { //'N' calls the lose function, ends program
		cout << "Well, that's too bad.\n";
		cout << "Exiting...\n";
		lose(); //calls lose function which is the end of program
	} 
	}
};

int main() //start of program
{
	cout << "Hello.";
	cout << "Would you like to play a game?[Y/N]\n";
	cin >> response;				//'Y' calls class instructions
	if (response == 'Y' || response == 'y') {
		cout << "Great! Let's begin.\n";
		Instructions call1;
		call1.playerInstructions(); //calls class instructions
	}
	else if (response == 'N' || response == 'n') { //'N' calls lose function, ends program
		cout << "Well, that's too bad.\n";
		cout << "Exiting...\n";
		lose();
	} 
	return 0;
}

int lose(){
	cout << "Sorry, you lose. Better luck next time.\n"; 
	cout << "Type anything and press enter to close";
	cin >> response3;
	return 0;
}

int win(){			//user only reaches this after class Game3 is completed
	cout << "You are very excellent at this.\n";
	cout << "You win!";
	cout << "Type anything and press enter to close";
	cin >> response3;
        return 0;
}

[ne555]

none of your member function uses the state of the object, ¿why are they member function?

With a couple of exceptions, your comments don't add anything
> int win(){ //user only reaches this after class Game3 is completed
that correspond to your current flow. It has nothing to do with what the function does.
And if that's supposed to be a precondition, then it's quite error-prone.

> win(); //calls win function which is end of program
there is nothing especial in `win()' that would terminate the program (like an `exit()' call)
it just happens to be the last called function.


Note how a lot of your code is repeated. Consider the modifications that you need to do in order to add another question.


Also, you should limit the scope of your variables. There is no justification for your globals

[MatthewRock]

Comments should say
a) things that you may not know while looking at code
b) things that are in code, but are harder to get
c) things that explain things so you know what and why without reading whole code or asking author.

Therefore, comment at int main:

int main() // start program 

is just idiotic. Everyone who reads C++ code knows that program execution starts with main function - why list obvious things?

Instead of doing comments like this(code I come up with, nearly nothing to do with code above):

int xyz; // declaring int xyz 

which is obvious when you look at it, you may want to write something like:

int xyz; // variable that will hold user's input and process it in ProcessInput(); 

Now you know what is the role of xyz.

Comments should explain logic behind actions, not read code.

I'd rather comment main like this:

int main()
{
	cout << "Hello.";
	cout << "Would you like to play a game?[Y/N]\n";
	cin >> response;				
       //Player wants to play game
	if (response == 'Y' || response == 'y') {
                //Start game
		cout << "Great! Let's begin.\n";
		Instructions call1;
		call1.playerInstructions(); 
	}
	else if (response == 'N' || response == 'n') {
                //Player doesn't want to play game
		cout << "Well, that's too bad.\n";
		cout << "Exiting...\n";
                //wait for input and exit
		lose();
	} 
	return 0;
}

Something like that; don't read code in comments; extend it.

+all ne555 said

[FuryEnder]

Thanks guys, this certainly helps.

[newbieg]

I've just finished a college class in beginning c++, and the instructor's idea of good code commenting is to have all comments about a function directly above it's definition, so when a coder sees a function they don't understand in main they can click on "go to definition" and read about what it does.
The instructor says that comments inside of a function make the code look sloppy and can make it harder to read overall. I can't really tell you if he was absolutely right, but it does seam to help me when I've got large code to write out.

/*
 A simple program to output the words hello world"; 
There should be a comment at the top of a program that explains it's general purpose, 
and how to use it. For a larger program this should be about 150 - 200 words long. 
*/
#include <iostream>

using namespace std;

void sayHi();

int main()
{
    sayHi();
}




/*  sayHi() outputs the words "hello World" to the console.
*  No input is required, no variables get changed.
*  For a smaller function 10 - 15 words should suffice
*  For more complex functions this can be over 50 words long.
*  The goal is to explain what the function does and what changes it makes
*   to the variables it contains and returns.
*/
void sayHi()
{
    cout << "Hello World";
}

This is a short example of what I mean, but the idea is that you don't want to explain what each and every if/else statement does, if you name your variables well then most coders can work out what they do pretty quickly, what you want to do is explain what the big plan for that function is. The other side of the coin is that each of your variables and functions should try to be descriptive of what they do or what they hold so that when you look at a block of code you can almost read it like English.

His scoring system was this;
1 Comments 20%
2 Appearance (e.g. Whitespace, Wraparound) 10%
3 Identifier Names 10%
4 Decomposition 20%
5 Indentation 10%
6 Simple Code/No Repeated Code 20%
7 Miscellaneous 10%

So basically he put a lot of heavy weight on the look of the code and the readability of the code, and less weight on if the code actually works or not. I found myself spending more time writing the comments than I ever did in writing the code.

(decomposition was his word for appropriate break-down and use of functions)