I’d like to discuss potentially updating the say instructions at
I’m reworking the Racket implementation for say and I found the canonical instructions confusing because they heavily focus on implementation details but are inconsistent. Six examples are given in step 1, but only one has the expected output. Two of these examples are also outside of 0 to 99, but we’re not told what to do with those numbers until subsequent steps.
Step 2 discusses breaking a number into a list of thousands, but it’s unclear if this covers numbers under a thousand or not. So it’s unclear what to do with numbers between 100 and 999. This step also reads as if I’m supposed to return the list at this point for numbers above a thousand, but that’s not true.
Step 4 doesn’t mention what’s changed between step 3 and 4 so we have to figure it out. We’re using 12345 here when we were using 1234567890 before which makes this a bit more complicated.
The extension section doesn’t seem particularly relevant to the exercise except maybe if the speak program was the inspiration. If so, I think that should be part of a potential introduction, but that’d be a separate PR.
This description in steps is a bit off for a practice exercise and focuses too much on just one of possibly many implementations.
I remember having some difficulty understanding what was expected the first time I solved it.
I think the description would be much clearer if it just described the expected result with some examples. And maybe added some story to motivate the exercise, although I don’t think it’s necessary here.
I don’t see any “implementation details” in these instructions. Instead I see:
An exercise asking for a particular algorithm (like sieve is one for primes)
A structure showing how to divide a problem into smaller problems and then combining the parts to a whole
An exercise bridging the gap between concept exercises (steps and focus on one concept) to most practice exercises (no hints on how to step towards a solution and total freedom of implementation)
I would suggest to emphasize these properties in the first paragraph of the instructions. And of course make the steps clearly connected to these ideas and distinct enough to make sense.
The main difference between sieve and this one is that the sieve algorithm is specific and well-known, so it’s important to explain it in detail. In contrast, the say exercise suggests an algorithm to make implementation easier, but correctness doesn’t depend on following that specific approach.
So the question is whether we should keep the proposed algorithm or allow people to implement their own. Given the already existing issues, i think it makes sense to update the instructions and remove it.
Your friend NAME volunteers as a local librarian, and they teach a financial literacy class.
Some of the students are visually impaired so NAME must read out the numbers.
Your friend takes pride in their pronunciation, but they have trouble reading out numbers.
To help them, you decide to convert these numbers to words.
Instructions
Your task is to help NAME by implementing their number-to-words conversion system.
Given a number from 0 to 999,999,999,999, you need to write that number in English words exactly as your friend should say it out loud.
0 -> “zero”
1 -> “one”
12 -> “twelve”
123 -> “one hundred twenty-three”
1,234 -> “one thousand two hundred thirty-four"
- Your friend NAME volunteers as a local librarian, and they teach a financial literacy class.
+ Your friend NAME volunteers as a local librarian, where teach a financial literacy class.
- Given a number from 0 to 999,999,999,999, you need to write that number in English words exactly as your friend should say it out loud.
+ Given a number, you need to write that number in English words exactly as your friend should say it out loud.
+ NAME expects to use numbers 0 to 999,999,999,999.
This lays out the expected inputs without specifying the inputs/tests. This allows tracks to decide if they want to test numbers outside that range or not without conflicting with the instructions.
Sounds reasonable. The introduction seems a bit contrived now that I look at it. Maybe the yet-to-be-named friend is calling out ticket numbers like at a deli counter or some sort of registrar.
Introduction:
At the busiest deli in town, your friend NAME works the counter, slicing, weighing, and wrapping orders for a never-ending line of hungry customers. To keep things moving, each customer takes a numbered ticket when they arrive.
When it’s time to call the next person, NAME reads the number out loud, always in full English words to make sure everyone hears it clearly.
Instructions:
Given a number, your task is to express it in English words exactly as your friend should say it out loud. NAME expects to use numbers from 0 up to 999,999,999,999.
I do not want to update the canonical tests. I’m not aware of any guidance that examples must also reflect the canonical data. 12 is a valid input according to the rules so it doesn’t contradict the rest of the instructions and its inclusion doesn’t contradict the test suite.
I wouldn’t include this in the instructions. The instructions often provides examples. Every exercise has tests which covers multiple cases and provides the requirements. That doesn’t need to be explicitly called out in the instructions.
Alright, any objection to tasx’s proposed text being PRed? As Isaac noted, we’ll want to drop the last line about checking the tests. The last thing to do would be to fill in the friend’s name. Yaʻqūb referring to al-Kindi - Wikipedia seems appropriate, but it doesn’t have to be a reference if someone else has a name to suggest.
It’s not a big deal either way but it might be nice to spread names across the alphabet range. I suspect most the examples use names starting with A, B or C … though I haven’t verified.
I also like the new instructions (minus the whole check the tests line).