Fix the story for ResistorColor

[emcoding]

The story of the second exercises in the series ( #1466 ) needed adjusting.
When that is sorted out, let’s use the lessons learned to improve on the existenting one.

[emcoding]

I am currently working on a new description for the Resistor Color exercise and series.

It's an examplar for how the Product Team wants in future exercise descriptions, as discussed with regard to Resistor Color Duo.*

Please add your wishes/suggestions to the comments, so they can be taken into consideration for the rewrite.

• Other discussions:
  resistor-colors: add new exercise #1466 (comment)
  Tricky Triplets - a storified replacement for Two Fer #1470

[emcoding]

Previous suggestions for this exercise description:

• Add instruction Resistor Color: Additional info for problem spec #1548
• Display of the mapping resistor-color-duo description leads implementation #1524
• Explicitly name that a band has a color and a position (from live discussion w @SleeplessByte)
• Avoid 'encoding' ResistorColorDuo: Remove unclear mention of "encoding" ruby#972

[emcoding]

Discussion copied from the PR:

@yyyc514 said:

Was the reference table really an issue? Are we purposely trying to drive people away from hash based solutions?

@kotp answered:

I believe we are trying to not push Hash unduly. Since Hash is meant to be introduced later in the track, we are trying to have the exercise draw other solutions. So "drive away" is perhaps a little harsh, but "not encourage" is probably a better description.

"Not encourage" was what I was going for. Therefore I avoided to suggest either. I agree with @kotp, especially for the Ruby track.
Other tracks may need this exercise(s) for other goals, by the way. In Ruby, Resistor Duo is a level 1 exercise, but in other tracks it could be positioned on level 2. A track can use the hints.md file to add a suggestion (or a requirement) for a specific datastructure. That may differ depending on the level they use it.
(FYI: the hints.md file is autogenerated into the readme = the instructions students see.)

[joshgoebel]

Such nuance. I follow the point, now I just think the spec/instructions themselves are made considerably WORSE by not including what was a very simple and useful mapping table - to help understand the issue (surely that's why it was included in the first place). The capitalization and "encoded" wording were issues for sure, but the table was a very useful part of the spec/instructions.

I guess making the specs worse in service to the goal of discouraging a specific solution rubs me the wrong way a bit. I'm not sure there should be any good reasons to make the specs worse/less clear.

[SleeplessByte]

The problem with the mapping table it that it completely hides the fact that there is more information than "colour -> number": the position of said colour. I proposed an entire table, but I also instantly said "this is probably too much information". I think that the latest iteration is a step towards the right direction, if not a pretty good near-final step.

Note that the above says nothing about the data-structure. My suggestions were not based on students using hashes/objects or arrays/lists, but the fact that the mapping was incorrect.

[joshgoebel]

The problem with the mapping table it that it completely hides the fact that there is more information than "colour -> number": the position of said colour.

OK... How does removing the table improve this situation any? How does the replacement ordered list of colors address this at all? It seems you've identified a problem, but then that the changes we'd made don't truly address it at all.

[other than the first early verbiage change a the top, but nothing about that necessitated changing the table]

[joshgoebel]

I'd suggest two tables... one dealing with the mapping to color and a second making it clear the colors/numbers are sequential. Isn't that often exactly how you see this done in diagrams explaining this?

One illustration to show the mapping a second to show that the sequencing matters.

[reddtoric]

The current blob of text displayed for Resistor Color exercise (Introduction section as well as the README file) is this:

Resistors have color coded bands, where each color maps to a number. The first 2 bands of a resistor have a simple encoding scheme: each color maps to a single number.

These colors are encoded as follows:

Black: 0
Brown: 1
Red: 2
Orange: 3
Yellow: 4
Green: 5
Blue: 6
Violet: 7
Grey: 8
White: 9
Mnemonics map the colors to the numbers, that, when stored as an array, happen to map to their index in the array: Better Be Right Or Your Great Big Values Go Wrong.

More information on the color encoding of resistors can be found in the Electronic color code Wikipedia article

rather than the description found in the main repo: resistor-color/description.md

[SleeplessByte]

@reddtoric which track?

[reddtoric]

@SleeplessByte Woops, C# track

[SleeplessByte]

You probably want to open an issue in https://github.com/exercism/csharp to sync their description with the canonical you found.

[jhaand]

For the C track I found the last test very confusing. It was very easy to map the mnemonics to an enum for the first 3 tests.

But the last test has no signature for the colors() function. And the solution requires to return an array of values on the heap. (static array) I find these quite advanced topics for an easy assignment without any hint.

Which invites people to look up solutions.

[siebenschlaefer]

@jhaand As a mentor on the C track I agree.
But that has nothing to do with this language-agnostic problem specification, more with how the exercise was translated to C, and is therefore slightly off-topic.
You might want to raise this issue on the C track or in the forum.

[jhaand]

This has been picked up in.
exercism/c#840 (comment)
and https://forum.exercism.org/t/exercise-resistorcolor-is-confusing-or-too-difficult/2461