Philosophy of problem descriptions vs. test suites, using "word-count" as an example.

[derifatives]

This is perhaps more of a user report than anyone else. I had a very unpleasant time with word-count (in Haskell). I opened an issue describing it, but this is clearly the right place, so I'll repeat it here:

Reading the problem, it sounds like a fun little problem that is basically about building a function that turns a list into an association list of counts: [a] -> [(a, Int)]. In actuality, I spent the vast majority of my time fiddling with parsing to give the desired answers. This experience has been repeated across quite a few problems:

• The initial description of the problem is vague. (Is this intentional to teach people about dealing with vague specs?) Here, for instance, we're given one hypothetical example and the desired output, and the description of the problem is high level: "a function that takes a text and returns how many times each word appears," with no definition of "text" or "word".

• The actual problem contains some set of additional concerns that are not part of the spec, are only discoverable via trial and error or reading the test file, and don't seem especially complete or coherent. In this case, you had to know that lowercase and uppercase letters are the same, that numbers with digit characters can occur as words, that commas may or may not have spaces after them, that quotes inside of words are part of the word but quotes around words should be removed, and that punctuation other than commas or quotes should be removed. It's not clear whether I ought to deal with mixed alphanumeric words or quotations that are longer than one word, since those aren't part of the test suite.
  Is this all intentional or just sloppy? I'm finding that I'm spending most of my time on a bunch of these problems dealing with parsing issues which weren't part of the problem description. Thoughts?

My opinion is that:

• An ideal description of the problem should be a full spec. It should be possible to write a program that passes the test suite by reading the spec.
• Problems that seem like they should be of algorithmic interest (figuring out what data structure to use, finding an efficient algorithm or data structure) should not require large amounts of tricky parsing.

My reasoning is simple: my delight on reading the problem turned into frustration when solving the problem, and it's easy for me to imagine others having the same experience.

In the particular case of "word-count," I think it would benefit the problem if many of the difficulties I mention above are removed, and the tests only contained letters (possibly upper and lower-case). I would be willing to improve the documentation and simplify the test suite if people think this is worthwhile.

[petertseng]

Although for word-count in specific I could go either way, in general I support better specs.

This may be a personal thing, but I like to go into things (projects, games, whatever) generally knowing what lies ahead. One could argue "Oh, well you should just read the tests anyway if you want to know what's coming up", and it could be that some requirements are better expressed in code than prose, but I imagine that for other requirements it is the opposite.

I observed in exercism/go#189 another case when a requirement present in the test suite but not present in the README caused frustration.

I understand that in the business there are often times when requirements change after work has started, for various reasons. It certainly can be valuable to learn to deal with that. It may be the case that Exercism decides to keep some of these situations for that purpose. My hunch is, though, that ideally it would be rarer.

I don't have much to back this statement up with, but it seems to me that having clearer specs would aid the goal of gaining fluency.

[yawpitch]

@derifatives would #1542 have addressed your issues with word-count?

[derifatives]

Looks good!

…

On Thu, Jun 27, 2019 at 3:34 PM Michael Morehouse ***@***.***> wrote: @derifatives <https://github.com/derifatives> would #1542 <#1542> have addressed your issues with word-count? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#869?email_source=notifications&email_token=AGHDJ4CLZ3EAUHXT23T3553P4UI23A5CNFSM4DTWGMMKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODYYEUPQ#issuecomment-506481214>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGHDJ4GI5V6F3645DHD46ZTP4UI23ANCNFSM4DTWGMMA> .