Haskell Zipper exercise instruction has fallen out of sink with the tests and the solutions.
Instruction is now misleading and need an update.
I created an issue on github, the issue was promptly closed to my frustration.
Originally, I wanted to do the fix myself, but it looks that help is unwelcome recently.
The topic is similar but not covered by
We use the forum to discuss and track issues, not Github.
You may want to read:
Practice exercises, by and large, pull from a canonical problem spec and changes should generally move in the direction of the spec.
After reading those resources, I believe this track may welcome a PR. @ErikSchierboom appears to be the acting maintainer for the moment there.
Thank you for telling me of canonical_proble_spec.
I checked the canonical spec for Zipper exercise and found the same issue there:
Symptoms:
exercises/zipper/description.md mentions rose tree and zipper operations ( … prev, next, … , delete )
exercises/zipper/canonical-data.json uses a binary tree and does not mention those operations, but uses ( left, right ) instead.
Therefore, the problem found is present no only in Haskell track, but in exercism/problem-specifications as well.
The change of the instruction text towards the current test implementation may hurt only the exercise author’s expectations. If we do the other way around, it will splash all the students who have solved the exercise.
Can you explain in detail what you think the issue is?
Dear Isaac, I think I did explain.
The exercise instruction asks a student to implement certain set of functions.
When student opens the editor, the file of the source code contains a different set of functions then what instruction talks about.
The data structure types in instruction and in code are also slightly different.
The concrete names are specified in my message above.
I think we all can imagine how it looks like when the documentation does not match the implementation.
Rather than saying “they are different” can you be explicit about what is different? I have a hard time reading images so it would be helpful to be specific and detailed with what is “different” or “out of sync”. Saying “it’s different” doesn’t explain what is different or what the issue is.
Dear Isaac,
Sorry, but I feel strongly demotivated by your requests for a detailed diff.
It seems like you are unwilling to go to the exercise and read,
and also unwilling to see the details in the image.
But let me persevere for a while.
instructions.md file is https://raw.githubusercontent.com/exercism/haskell/main/exercises/practice/zipper/.docs/instructions.md
Zipper.hs file is https://github.com/exercism/haskell/blob/main/exercises/practice/zipper/src/Zipper.hs
In line 3 of the instruction.md, a binary tree type is mentioned once and never more.
The rest of the instruction file discusses an example of a “Rose Tree” and not “Binary Tree”, that is somewhat relevant to the task, but is also confusing.
instructions.md line 13: prev function is introduced, it is absent from the Zipper.hs.
Zipper.hs line 30: left function is introduced instead of prev function of the instructions.md.
instructions.md line 15: next function is introduced, it is absent from the Zipper.hs.
Zipper.hs line 33: right function is introduced instead of next function of the instructions.md.
instructions.md line 19: insert_before function is introduced, it is absent from the Zipper.hs.
Zipper.hs line 33: setLeft function is introduced instead of insert_before function of the instructions.md.
instructions.md line 21: insert_after function is introduced, it is absent from the Zipper.hs.
Zipper.hs line 33: setRight function is introduced instead of insert_after function of the instructions.md.
instructions.md line 23: delete function is introduced, it is absent from the Zipper.hs.
A student can imagine, that a Binary Tree can be represented by a “Rose tree” where each node has at most 2 children.
They can also think that the functions were renamed between instructions.md and Zipper.hs.
But the difference between e.g. functions prev and left is deeper: instructions.md prev description suggests navigating to the left among the sibling nodes on the same level,
whereas Zipper.hs left is expected to descent one level down.
In the absence of comments in Zipper.hs, it is only Tests implementation what can guide a student out of their confusion.
In this context, instructions.md lines 8-25 only cause the confusion.
I have expressed my readiness to edit instructions.md lines 8-25 so that they discuss the relevant example and contain relevant function names and explain relevant function semantics.
Now how explicit is this ?
Thank you for the detailed textual context. I suspect that it explains what others may be able to see in the image, while those that are not only willing to see the image but even excited to see the image, however they may be unable to due to not having the privilege of simply being able to, can now understand better what the image probably describes very clearly to those that can see it.
I am 99% sure that this person has already read the document, the exercise, and is familiar with it, perhaps too familiar with it, and so does not “see” the problems that fresh eyes like yours would see, and since they have already helped others to contribute changes, I would not assume an unwillingness (or even an unwillingness to do what is simple for many people, to look at an image) to analyze the problem with your help.
I am glad that you have persevered through the demotivational part of this, and am sure that now the details are brought to light, even for those of us that may live in less light than many people, we can now see what it is that you see.
Much better, thank you.
right, left while file B has prev, next” is short, succinct and very clear about what the difference is.To summarize,
Does that sound about right?
Exercism does take a TDD approach. The expectation is that the tests do drive the expectations and requirements.
That said, I don’t see any reason we couldn’t align the language between the instructions and tests. I believe it would make more sense to update the instructions than to update the tests where possible (since updating the tests would break existing solutions). I, for one, would welcome a PR to improve this exercise. My suggestion would be roughly along the lines of this: