Improve instructions of Book Store exercise

Hi,
I just started out on the Book Store exercise, and the instructions are rather poorly-formatted. In particular:

  1. In line 37 and other lines, there’s an unnecessary + at the beginning.
  2. The function name is given as Cost when it’s cost.
  3. On many lines like no. 46, the double equals operator is used, when a single equal operator semantically makes more sense.
  4. Dashes are, for some reason, used instead of the multiplication operator.
  5. The discount bit isn’t made clear in the example. On line 46, the instructions say 8.00 - 2.00, but to explain the 25% discount, it’d be better to say 8.00 * (1 - 0.25) or the like.
  6. In the last paragraph, it says “Cost will return”, seemingly speaking about the function cost. In that case, it’d make more sense to use monospace and lower case: "cost will return`.
  7. On line 17, there’s a colon after “Note” which is grammatically incorrect. The colon should be removed.

There are other minor issues about the language is phrased, all of which I’ll correct and submit in a PR if I get the green flag. Thanks!

That + is not exactly redundant. However, I would like a space between it and the rest. Maybe a bullet list isn’t ideal here.

Green light is given for specific changes, not for undiscussed ones.

A space in point 1, OK. What about the rest of the points?

I agree with all of those.

Anybody else? @ErikSchierboom, can I implement these?

Hold on a bit. Let’s discuss these some more.

Maybe replace --> with :?

Where is that?

I agree that this could be clearer, but 8.00 * (1 - 0.25) isn’t clearer to me to be honest. Maybe 8.00 - (0.25 * 8.00) = 8.00 - 2.00?

Agreed.

These are specific to the JavaScript track: javascript/exercises/practice/book-store/.docs/instructions.append.md at main · exercism/javascript · GitHub I don’t know if they are open to PRs.

If a consensus is reached here, then a PR may be opened. Please tag me or Erik afterwards so we can re-open the PR.

I haven’t opened the PR yet, but I’ll let you know when I do!

About #1: should I remove the plus or add a space after it, as @MatthijsBlom suggested?

Can we use a single equals operator as proposed? Or shall we use a colon instead of --> and a single equals instead of a double equals?

Check lines 46, 47, 63, and 64.

Great, we’ll do that, then!

But you agree? I’ll submit a PR and link back to this topic, hopefully it’ll be merged.

Note: javascript’s introduction.md is not in sync with problem-specifications’s.

Probably first problem-specifications should be improved, and then javascript should be updated.

Also: this exercise introduction will likely be entirely overhauled this year anyway.


I propose:

 One way of grouping these 8 books is:
 
-- 1 group of 5 --> 25% discount (1st,2nd,3rd,4th,5th)
-- +1 group of 3 --> 10% discount (1st,2nd,3rd)
+- 1 group of 5 (1st, 2nd, 3rd, 4th, 5th), plus
+- 1 group of 3 (1st, 2nd, 3rd).

 This would give a total of:

-- 5 books at a 25% discount
-- +3 books at a 10% discount
+- 5 books at a 25% discount, plus
+- 3 books at a 10% discount,
 
 Resulting in:

-- 5 × (8 - 2.00) = 5 × 6.00 = $30.00
-- +3 × (8 - 0.80) = 3 × 7.20 = $21.60
+- 5 × (100% - 25%) × $8 = 5 × $6.00 = $30.00, plus
+- 3 × (100% - 10%) × $8 = 3 × $7.20 = $21.60

-For a total of $51.60
+for a total of $51.60.

(This is only the first half; the second half is analogous.)

2 Likes

Thanks for pointing out that the problem-specification and javascript versions are not in sync, MattijsBlom! The former doesn’t have dashes instead of multiplication operators, an important flaw in the JS version.

To come to your proposal: I’m not sure where you’re getting this code. The code I see in problem-specifications is this, no double hyphens or a plus character before the hypen character:

One way of grouping these 8 books is:

- 1 group of 5 --> 25% discount (1st,2nd,3rd,4th,5th)
- +1 group of 3 --> 10% discount (1st,2nd,3rd)

This would give a total of:

- 5 books at a 25% discount
- +3 books at a 10% discount

Resulting in:

- 5 × (8 - 2.00) = 5 × 6.00 = $30.00
- +3 × (8 - 0.80) = 3 × 7.20 = $21.60

I’m also dubious about your usage of “plus”. The instructions clearly say that it’s a group, so we don’t need a plus character or word to show that it’s grouped together. I propose we remove the plus thing altogether. However, I like your discount code, and if we’re agreed over the plus thing, I’ll submit a PR.

1 Like

I cloned problem-specifications, edited it, then exported the diff.

The first character on every line of a diff indicates what happens with the line. A space indicates that nothing changes, a - indicates that the line be removed, and a + indicates that the line be added.

BTW, I think your usage of plus makes sense.

I’ve opened a PR on problem-specifications, but many of the issues listed here are specific to the javascript track, and I’ll open a subsequent PR there after this is merged, @SleeplessByte, thanks!

If a consensus is reached here, then a PR may be opened.

Was a consensus reached here?

Well, the two people participating in the discussion agreed, so that’s a consensus, right? If you disagree with any of the listed points, I’d be glad to reiterate.

Consensus should be read as, “consensus of the maintainers”. Not “any two people agreed upon something”. Consensus generally means majority or all the people are in agreement, not just more than one person.

That’s true. The only maintainers here are @ErikSchierboom and you. What do you both think?

I think we should listen to what has already been said.

Hold on a bit. Let’s discuss these some more.

If a consensus is reached here, then a PR may be opened. Please tag me or Erik afterwards so we can re-open the PR.

There’s plenty of other people who may also have something more to contribute here, given some time, even if they aren’t deciders on the PR.

For the equations, I’m personally more in favor of Erik’s approach than Matthijs’ approach

+ 5 × ($8 - $8 × 0.25) = 5 × $6.00 = $30.00, plus
- 5 × (100% - 25%) × $8 = 5 × $6.00 = $30.00, plus

Otherwise, I think Matthijs’ diff is excellent. However, I notice the PR and Matthijs’ diff aren’t quite the same.

I agree, I’ll commit and change it to the first equation.

What other differences are there between the PR and Matthijs’ diff which you think we should change?

1 Like

What do others think? Is this change worth implementing?

@IsaacG, I’ve committed the Erik’s equation version.