Homework to display a square and calculate tips

Here's a simple school assignment I did:


Problem 1: Write a program that asks the user for a positive integer
no greater than 15. The program should then display a square on the
screen using the character “X”. The number entered by the user will be
the length of the side of the square. For example, if the user enters
5, the program should display the following:

XXXXX 
XXXXX 
XXXXX 
XXXXX 
XXXXX

Problem 2: Imagine that you and a number of friends go to a restaurant
and when you ask for the bill you want to split the amount and the tip
between all. Write a function

double CalculateAmountPerPerson(double TotalBill, double TipPercentage, int NumFriends)

that takes the total bill amount, tip percentage (e.g., 15.0 for a 15%
tip), and the number of friends as inputs and returns the total bill
amount as its output.


Write a main function that asks the user for the total amount of the
bill and the size of his/her party (i.e., number of friends) and
prints out the total amount that each person should pay for tip
percentages of 10%, 12.5%, 15%, 17.5%, 20%, 22.5%, 25%, 27.5%, and
30%. Your main function should use a loop and invoke the
CalculateAmountPerPerson function at each iteration.

My code:

```
#include
#include

void menuPrompt();
short getMenuSelection();
void program1();
void squareLengthPrompt();
void displaySquare(int, char);
void program2();
void billPrompt();
void numPeoplePrompt();
double CalculateAmountPerPerson(double, double, int);
const short PROGRAM_1 = 1;
const short PROGRAM_2 = 2;
const short EXIT = 0;

int main(int argc, char *arv[]) {
while(true) {
char menu = getMenuSelection();
switch (menu) {
case EXIT:
exit(EXIT_SUCCESS);
case PROGRAM_1:
program1();
break;
case PROGRAM_2:
program2();
break;
default:
std::cout > selectio

The code is not self-documenting, because the problem description is non-trivial and involves what you'd call "business logic". That is, you're not trying to perform some technical operation (like a cache, or a data structure, or a parser), but you're following rules defined by someone else. Each of those rules has to be programmed in, of course, but without describing WHY they have been put in, you'll always need the problem description along with the code to make sense of the code.

Imagine you had posted your question without the problem description. Would we have been able to guess what the goal of your assignment was?

Personally, yes, I think so. This is because if I were to run your program, it asks clear questions and prints a clear result. It does require a non-trivial time investment, though.

You get


"Enter the length of the side of the square (Between 1 and 15): "

As output on the screen, you enter a number, you get a square. Program 1 will print a square.

And seeing something like

for(auto tipPercent: TIP_PERCENTAGES){
    amountPerPerson = CalculateAmountPerPerson(totalBill,tipPercent, totalPeople);
    std::cout << "With the tip percentage of " << std::fixed << std::setprecision(2)
        << tipPercent*100 << "%, each person pays " << amountPerPerson
        << " from a $" << totalBill << " bill. " << std::endl;
}

In the code tells me that program 2 is for splitting up a bill.

In that sense, the code is self documenting. We don't need the problem description. We can see what the code does, because we can execute it.

What comments are for, then, are not for explaining what the code does. That understanding can already be achieved by, well, reading and executing the code.

Comments have 2 main uses, in my opinion: First, to explain the why of the code (why does the code do what it does). Second, to help speed along the understanding the code. Basically, rather than making me read and execute the entire program, spending lots of time, you simply put the purpose of a part of code in a comment, and I can read what the code does via condensed comments. Like reading a recipe instead of watching someone actually cook something.

The act of making code self-documenting, then, is to put these comments into active code. Putting the why into code is hard; the only places you can possibly do this is in error messages - "number of people must be greater than 0, cannot split bill between 0 or negative people" - stuff like that explains why there is a totalPeople <= 0 check. I don't recommend going out of your way to do that; comments are for the programmer and output is for the user.

Putting the how comments into code is a lot easier. You can use function names for this.

Compare:

amountPerPerson = CalculateAmountPerPerson(totalBill,tipPercent, totalPeople);

and

s = calc(sum, pct, num);

One is clear to understand, the other could mean anything. Yet it can even make sense after we give it a comment...

double s; //share per person
    s = calc(sum, pct, num); //calculate share per person using sum costs, tip percentage and number of people

So you've, in essence, already done this "importing of comments".

There are still a few improvements to be made.

For instance...

void program2() {
    const float TIP_PERCENTAGES[] = {.10, .125, .15, .175, .20, .225, .25, .275, .30};
    double totalBill = 0;
    int totalPeople = 0;
    double amountPerPerson;
    while (totalBill > totalBill;
    }
    while (totalPeople > totalPeople;
    }
    for(auto tipPercent: TIP_PERCENTAGES){
        amountPerPerson = CalculateAmountPerPerson(totalBill,tipPercent, totalPeople);
        std::cout << "With the tip percentage of " << std::fixed << std::setprecision(2)
            << tipPercent*100 << "%, each person pays " << amountPerPerson
            << " from a $" << totalBill << " bill. " << std::endl;
    }
}

program2 as a whole is hard to understand. You have to carefully read what it does to see what it does. Had you instead renamed the function to runBillSplitterProgram, we'd have gotten a hint of the meaning already.

Internally, you have tried splitting certain sections up, but you're only done this for the long strings.

We can do slightly better by not separating based on code length, but on functionality:

//in runBillSplitterProgram
double amountPerPerson;
double totalBill = askForTotalBill();
int totalPeople = askForTotalPeople();

//as separate functions        
double askUserForTotalBill() {
    double totalBill = 0;
    while (totalBill > totalBill;
    }
    return totalBill;
}

int askUserForTotalPeople() {
    int totalPeople = 0;
    while (totalPeople > totalPeople;
    }
    return totalPeople;
}

It's a shame one is a double and the other is an integer, or you'd been able to merge both into some sort of askUserForValue function, keeping billPrompt as a function which calls askUserForValue with a lengthy string.

Technical comm

StackExchange Code Review Q#135569, answer score: 10