Commenting on my code [closed] - c++

Question

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
I'm having difficulty commenting on my code for a blackjack app for c++. I have coded it but now I am confused as to what to put in for comments, my instructor is frugal when it comes to commenting.
Thanks for any and all help! :)
here is my code:
#include <iostream> // in/out for form
#include <ctime> // uses time for randomizing
#include <Windows.h> //
using namespace std; // prevents redundancey of ::STD
char enter[1]; //
int hand[52] = {}, dealer[52]; // array of 52 for 52 cards that holds zero
int GetScore(int param) // function prototype that calls getscore
{
int score = 0; //
int temp[52]; //
if(param == 0) for(int i = 0; i < 52; i++) temp[i] = hand[i]; //
if(param == 1) for(int i = 0; i < 52; i++) temp[i] = dealer[i]; //
for(int i = 0; i < 52; i++) //
{
if(temp[i] == 0) break; //
if(temp[i] != 11)
{
score += temp[i];
}
}
for(int i = 0; i < 52; i++) // simple loop to ....
{
if(temp[i] == 0) break;
if(temp[i] == 11)
{
if(temp[i] + score <= 21)
{
score += 11;
}
else
{
score += 1;
}
}
}
return score;
}
void ShowDealersHand(int show) //
{
cout << "\n Dealer's hand: "; //
if(show == 1) //
{
if(dealer[0] == 11)
{
cout << "A [Not Shown]";
}
else
{
cout << dealer[0] << " [Not Shown]";
}
}
else
{
for(int i = 0; i < 52; i++)
{
if(dealer[i] == 0) break;
if(dealer[i] == 11)
{
cout << "A ";
}
else
{
cout << dealer[i] << " ";
}
}
}
}
void Blackjack()
{
for(int i = 0; i < 2; i++) //
{
int num, temp;
if(hand[0] == 0) temp = 0;
else temp = 1;
num = rand() % 10 + 2;
hand[temp] = num;
num = rand() % 10 + 2;
dealer[temp] = num;
}
ShowDealersHand(1); //
cout << endl << endl << " Your hand: "; //
for(int i = 0; i < 52; i++) //
{
if(hand[i] == 0) break;
if(hand[i] == 11)
{
cout << "A ";
}
else
{
cout << hand[i] << " ";
}
}
cout << endl << " Your score: " << GetScore(0) << endl << endl;
while(GetScore(0) <= 21)
{
cout << " Hit(h) or stand(s): ";
cin >> enter;
if(strcmp(enter, "h") == 0)
{
int card = rand() % 10 + 2;
for(int i = 0; i < 52; i++)
{
if(hand[i] == 0)
{
hand[i] = card;
break;
}
}
cout << " Your hand: ";
for(int i = 0; i < 52; i++)
{
if(hand[i] == 0) break;
if(hand[i] == 11)
{
cout << "A ";
}
else
{
cout << hand[i] << " ";
}
}
cout << endl << " Your score: " << GetScore(0) << endl << endl;
if(GetScore(0) > 21)
{
cout << " - ..BUST.. -" << endl ;
cout << "\n - !!House Wins!! -";
goto end;
break;
}
}
else if(strcmp(enter, "s") == 0)
{
cout << endl;
break;
}
system("pause > nul");
}
Sleep(2000);
ShowDealersHand(0);
cout << endl << " Dealer score: " << GetScore(1) << endl << endl;
if(GetScore(1) < GetScore(0))
{
while(GetScore(1) < 17 && GetScore(0) <= 21)
{
Sleep(2000);
int card = rand() % 10 + 2;
for(int i = 0; i < 52; i++)
{
if(dealer[i] == 0)
{
dealer[i] = card;
break;
}
}
cout << " Dealer's hand: ";
for(int i = 0; i < 52; i++)
{
if(dealer[i] == 0) break;
if(dealer[i] == 11)
{
cout << "A ";
}
else
{
cout << dealer[i] << " ";
}
}
cout << endl << " Dealer score: " << GetScore(1) << endl << endl;
if(GetScore(1) >= GetScore(0)) break;
}
}
end:
if(GetScore(1) > GetScore(0) && GetScore(1) <= 21)
{
cout << " - !!House Wins!! -";
}
else if(GetScore(1) == GetScore(0) && GetScore(0) <= 21)
{
cout << " * Tie * - !!House Wins!! -";
}
else if(GetScore(0) <= 21)
{
cout << " - !!!You win!!! -"; // outputs if you win
}
system("pause > nul");
system("cls");
}
void main() // no return on main for form to start
{
srand((unsigned int)time(0)); // randomizer unasigned initializer
cout << " *-*-*-*-*Zachattack's Blackjack*-*-*-*-*" << endl << endl; // Name of program outputs to user
Blackjack();
}

Answer 1

As they are, you comments are useless. Take, for example, this:
int hand[52] = {}, dealer[52]; // array of 52 for 52 cards that holds zero
Anyone that uses C/C++ is expected to know what that line is doing, without having to read the comment.
Instead of commenting what your code does ("this line declares an int"), comment why the code does what it does (what you were thinking when you wrote that code), or, if the algorithm is complicated, comment on how it does something, or document how to use your functions.
For example, your GetScore function takes has a parameter called param. I've no idea what values I am expected to give to param, so you should explain it: "when param is 1, this happens, when it is 0, that happens".
Another example: in your code you have a line Sleep(2000). Why did you use that function? Explain it in a comment:
// Sleep 2 seconds to make the game more exciting
Sleep(2000);
Always assume that the person reading your code knows how to use the language. Never assume that the person reading your code is able to understand your way of thinking about a certain problem.

Answer 2

Comments should explain why, not what.
So your comment for using namespace std; is unnecessary, because any C++ programmer will already know what the using keyword does.
However, for the GetScore() function, you've omitted to give the rules for totalling the score.
The comments should add value, not just duplicate things that are obvious from even a cursory look at the code.
Assume the person reading the code is familiar with the programming environment, but wasn't party to what was going on in your mind as you wrote it.
Here's an example I sometimes use - a piece of code with useless comments (can you work out what is going on here, and why?):
// Is the new selection end above the selection start?
if newSelEnd.Line < FSelection.SelStart.Line then
begin
// Is the selection start at the left margin and above the selection end?
if (FSelection.SelStart.Line < FSelection.SelEnd.Line) and
(FSelection.SelStart.Column = 0) then
begin
// Move the selection start down one line
Inc(FSelection.SelStart.Line);
And with helpful comments:
if newSelEnd.Line < FSelection.SelStart.Line then
begin
// The new selection end is above the selection start, so will become the
// top of the new selection.
if (FSelection.SelStart.Line < FSelection.SelEnd.Line) and
(FSelection.SelStart.Column = 0) then
begin
// The start of the selection was at the top of the old selection and the
// new line is above this, so the selection is about to change direction.
// Since the start column is 0 we assume the original selection was an
// entire line, so we keep the original line selected by moving the start
// position down one line.
Inc(FSelection.SelStart.Line);

Answer 3

Function/method purpose with parameters purposes
Magic numbers
Those are my most important rules about commenting. Optional is "why am I iterating/what am I looking for" about loops. Magic numbers is every declaration/condition that uses const values like GetScore(0) <= 21, or hand[52].
Those are places that should be commented even for yourself... It feels realy good when you look at your code after year or more and still read it without any problem.

Answer 4

Apart from the other answers, often, it is a good idea to get rid of a comment by replacing it with a named function:
// Find top-scorers:
for (Iter it=scorers.begin(), end=scorers.end(); it!=end; ++it) {
...
{
top.push_back (*it);
}
}
Instead, do:
const std::vector<Scorer> top = find_top_scorers (scorers.begin(),
scorers.end());
This decreases miss-maintenance (comments are not enforced and may get out-of-date) and reusability. Personally, I always endeavour for commentless code, as I am sick of out-of-date comments, when possible and sane.
Of course, in the example above, you should probably use std::partial_sort, std::partition or std::stable_partition.
Also, magic numbers should be replaced by constants instead, with the same argumentation about miss-maintenance and reusability:
const float x = radius * 3.14159...; // radius * pi
const float pi = 3.14159...,
x = radius * pi;