updated description of anagrams exercise

[BartMassey]

closes #1556, affects exercism/rust#86, exercism/rust#690

[ErikSchierboom]

Our Markdown style guide has a one sentence per line rule.
It is true that not many exercises do yet follow this guideline, but it might be good to apply that rule to this PR.
See https://github.com/exercism/problem-specifications/pull/1911/files for an example.

[BartMassey]

Sure, I guess.

Here is Python to partly automate this process. Text editors really don't deal with it.

You should add a check to your CI Markdown linter if you want to enforce this behavior.

[petertseng]

I can show that at least two tracks do not enforce that the elements are in the same order as in the original:

https://github.com/exercism/ruby/blob/main/exercises/practice/anagram/anagram_test.rb#L19 - since it sorts the list, the list may be in any order
https://github.com/exercism/rust/blob/main/exercises/practice/anagram/tests/anagram.rs#L6 - since it compares the sets, the sets need only contain the same elements, as sets have no concept of ordering

How shall we handle this? Shall we declare those two tracks, and all others who do the same, to be out of compliance? Or shall we allow for the possibility?

[BartMassey]

Good point. I'm fine with whatever.

I do think we should be clear in the generic description about whether we're thinking of the candidates and the result as a sequence, set, multiset or something else. If the result is to be a set or multiset, I think we should also specify that the candidates are: it would be confusing to change representations between the input and output. Having the input and output be "a sequence representing a set" seems to me to be a bit weird: if we choose a set representation, languages that don't support sets can always choose to represent them as lists and the tests can reflect that (by sorting or whatever).

One of my goals in rewriting the description was to not have to do it again, by being precise enough to clearly indicate exactly what is expected. If we choose to make the input and output a sequence, we need to specify:

• Whether duplicates can appear in the candidates

  • If so, whether duplicates should appear in the result
  • If not, whether words that differ only by case are different?

• What constraints, if any, there are on result ordering

Regardless, we need to clearly specify:

• What constraints, if any, there are on result letter-case
  • In particular, should the result case match the candidate case?

I'll wait for thoughts from others before trying again on this.

(Another thing I realized this morning while staring at my work is that I never really directly answered the question "Is 'StOp' an anagram of 'stop'?". My intent was no, but with your blessing I'll modify the first example or add a later example to reflect this.)

[ErikSchierboom]

How shall we handle this? Shall we declare those two tracks, and all others who do the same, to be out of compliance? Or shall we allow for the possibility?

I'd say that the set-based solution used by Rust actually makes the most sense. Why would there be an ordering in the results? That said, apparently the set-based approach is fairly unique. Personally, I think that we should probably allow for tracks choosing their own implementation.

I do think we should be clear in the generic description about whether we're thinking of the candidates and the result as a sequence, set, multiset or something else. If the result is to be a set or multiset, I think we should also specify that the candidates are:

This is a great goal, but not always as easy to achieve due to both historic reasons and tracks implementing exercises differently (which is often totally valid). Basically, any time you want to be really specific in the description, it makes it more likely that the description won't correspond to a track's actual implementation. I don't have a great solution unfortunately.

Another thing I realized this morning while staring at my work is that I never really directly answered the question "Is 'StOp' an anagram of 'stop'?". My intent was no, but with your blessing I'll modify the first example or add a later example to reflect this.

I think it shouldn't be an anagram. That seems to be the most consistent with the specs.

[BartMassey]

This problem is especially awkward because it has a whole bunch of implicit ASCII-English linguistics assumptions. The attempt to define these away by providing an explicit dictionary is an approach, but it does require establishing what the dictionary is and does. Dictionaries are fundamentally sets (really maps to definitions, but the definitions are usually irrelevant in word games): perhaps the right approach is to describe the input and output as sets here, and allow the various language versions to use implicit or explicit unordered lists as sets. That said, if the dictionaries are sets that means that the same word will not appear in them more than once, so the question of lettercase folding has to be settled: can a word appear multiple times in the dictionary with different lettercase combinations?

If the principals here reach consensus on these kinds of issues I'm happy to draft English as desired. I don't feel like it is good practice to have problem descriptions that conceal details of the actual problem, especially for new coders attempting simple-looking problems. This can lead to a ton of frustration as code fails tests for properties the programmer didn't know were being enforced and that they don't necessarily understand.

Sorry I couldn't be of more help clearing this up.

[petertseng]

If the decision were in my hands alone, I would say in the description that the candidate words are a set. If there is a track that makes a decision to instead use their ordered sequence type instead of their set type (for example, the ordered sequence type is more ergonomic to use, or a set simply isn't provided in the language or its libraries), I don't really foresee this drawing complaints of noncompliance, but I can't really say that my predictive power is any better than any average person's.

Do note that in https://github.com/exercism/problem-specifications/blob/main/exercises/anagram/canonical-data.json#L151 we already have a case where "candidates": ["BANANA", "Banana", "banana"], so we are allowing candidate words with different case to be considered distinct from each other.

I do note that we've never had a case where the expected result has ever needed to contain something like ["BANANA", "Banana", "banana"], so we're free to make whatever decision is easiest, or defer that particular decision.

We do say that BANANA is still not considered an anagram of banana, them being different casings of the same word.

It does occur to me, typing this now, that I see that there is an inconsistency.

• For set membership, word equality is case-sensitive, because the same word with different casing can exist in the same set.
• For the anagram test, word equality is case-insensitive, both because stop should not be an anagram of STOP and stop should be an anagram of POTS.

That is an interesting inconsistency, but I don't recall anyone having been confused by that, since they apply in different situations.

[ErikSchierboom]

Sorry I couldn't be of more help clearing this up.

Oh but this is very helpful! We're just in the process of figuring out the right words, which is hard.

I don't feel like it is good practice to have problem descriptions that conceal details of the actual problem, especially for new coders attempting simple-looking problems. This can lead to a ton of frustration as code fails tests for properties the programmer didn't know were being enforced and that they don't necessarily understand.

Yeah that can be very frustrating.

If the decision were in my hands alone, I would say in the description that the candidate words are a set.

Ah good idea, we omit the ordered-ness property and just refer to it as a "set". What do you think @BartMassey?

[BartMassey]

Making them be sets is fine with me. I think we should then correct ["BANANA", "Banana", "banana"] in the Javascript version, though. @petertseng did you want to file an issue and PR there, or shall I?

[ErikSchierboom]

Excellent 👍

[petertseng]

good idea to handle the ["BANANA", "Banana", "banana"] as an issue following this one. I'm not picky on who does it. If I don't see one a few days after this PR is merged I'll do it.