[Darts]: Mention what should happen when a dart lands 'on the line'

[KaiAragaki]

Though it's implied in the tests, it might be nice to include that if a dart lands on the border between one ring and the other (say it lands at 0, 5) that it should go to the higher values. If this is acceptable, I can make a PR to update the exercise.

[github-actions]

🤖   🤖

Hi! 👋🏽 👋 Welcome to the Exercism Python Repo!

Thank you for opening an issue! 🐍  🌈 ✨

•   If you are requesting support, we will be along shortly to help. (generally within 72 hours, often more quickly).
•   Found a problem with tests, exercises or something else??  🎉
    ◦ We'll take a look as soon as we can & identify what work is needed to fix it. (generally within 72 hours).

​          ◦ If you'd also like to make a PR to fix the issue, please have a quick look at the Pull Requests doc.
             We  💙  PRs that follow our Exercism & Track contributing guidelines!

•   Here because of an obvious (and small set of) spelling, grammar, or punctuation issues with one exercise,
    concept, or Python document?? 🌟 Please feel free to submit a PR, linking to this issue. 🎉

‼️  Please Do Not ‼️ ​        ❗ Run checks on the whole repo & submit a bunch of PRs.               This creates longer review cycles & exhausts reviewers energy & time.               It may also conflict with ongoing changes from other contributors. ​        ❗ Insert only blank lines, make a closing bracket drop to the next line, change a word               to a synonym without obvious reason, or add trailing space that's not an EOL for the very end of text files.         ❗ Introduce arbitrary changes "just to change things" .         ...These sorts of things are not considered helpful, and will likely be closed by reviewers.

• For anything complicated or ambiguous, let's discuss things -- we will likely welcome a PR from you.
• Here to suggest a feature or new exercise?? Hooray! Please keep in mind Chesterton's Fence.
  Thoughtful suggestions will likely result faster & more enthusiastic responses from maintainers.

💛  💙  While you are here... If you decide to help out with other open issues, you have our gratitude 🙌 🙌🏽.
Anything tagged with [help wanted] and without [Claimed] is up for grabs.
Comment on the issue and we will reserve it for you. 🌈 ✨

[bobahop]

I think the test_on_the_XXX_circle(self) tests are specific that the border hit counts higher, but I have nothing against making it clearer in the instructions. It's not my call, though.

[KaiAragaki]

A question more about the philosophy of these exercises: should we consider reading the tests as part of the exercise, or should one be able to successfully complete the exercise without ever reading the tests?

[IsaacG]

See https://exercism.org/docs/tracks/python/test-driven-development where the track explicitly discusses this issue.

Exercism's Python track utilizes TDD methodology in its exercises. Unit tests are already written. The tests may be viewed by the student to gather a more detailed understanding of what is required for a solution to pass. A solution stub may be provided to the student.

The test is the definitive embodied exercise requirement. The prose simply provides an overview and context.

[KaiAragaki]

Good point. I'll close the issue.

[BethanyG]

@KaiAragaki - I am going to reopen this issue, as I intended to have a discussion, but was delayed by other work. I'll chime in with more thoughts later today tomorrow my time. 😄 To your point about the exercise: students should be engaging with both the instructions and the tests. Instructions can't give every detail, but tests and stubs can't replace directions. As IsaacG has mentioned, we do strongly encourage TDD - we want students to look at and learn from tests. But we also want them to be able to parse specifications (directions) too.

@IsaacG - while you are technically correct, I think we should always consider suggestions from students - especially those new to the track when they say something needs to be clarified in the instructions or hints. Yes - we do indeed practice TDD, but that doesn't mean that because there are tests that instructions are frozen in stone, or that something can't be more detailed or amended. Please don't imply to students that that is the case unless we have a discussion first. It's likely that I and other maintainers of the track will agree with you - but some exercises have a history of issues or approaches that you might not know.

This exercise has already had a hints file added because of the issue linked above, as well as another issue on the same topic that I cannot locate right now. The upshot is that instructions are hard to parse for some students, and in trying to figure out the whole euclidian distance thing, they may miss the subtleties of what to do if the dart is on a line. I think the instructions might benefit from some clarification/further discussion in problem specifications, and might also benefit from an instruction append (maybe even with a diagram) here on the Python track. Remember: this exercise appears fairly early in the progression.

[BethanyG]

@KaiAragaki - Because this is a practice exercise, we have less leeway (actually, more complication) in editing problem instructions and tests. We pull both descriptions and test specification from the problem-specificaions repo using a tool called configlet. Test data is then run through a generator script to produce the Python test files. Problem descriptions are mostly taken as-is, or amended via instruction_append files on the track.

Changes to the main descriptions/instructions and test data are proposed/discussed cross-language track in problem-specifications. We try to keep both fairly generic and language agnostic. Once three or more track maintainers agree that a change is needed, it is PR'd there and then pulled down into various tracks.

Tests and instructions that are language specific are then added via additional_tests.json (example here) and instructions_append (involved example here)

TL;DR:

1. I think you have a point, and like @bobahop, I do think the test name is pretty specific, but the instructions would not hurt from a mention of a dart on the line.
2. Since problem specifications #1971 is already open as an issue, my first recommendation would be to comment there, and mention that in addition to clarifying the math, you also think that the instructions might benefit from wording about darts on the line between sections.
3. If people agree with you, the next step would be to propose a PR in problem-specs (and I think you'd get extra love for also addressing the math part).
4. Additionally/instead, we can consider making an instructions_append specifically for the Python track. This could include words and or diagrams (We support mermaid and SVG. Here is an example of a diagram that can be included.)
5. We can also consider adding to the existing hints.md file for this exercise.
6. Commenting in the test file is a tad more involved, since it requires editing the test generation template and re-generating the test cases. But that is also an option, if we think a comment there would help.

So let me know what you'd like to do. 😄

[KaiAragaki]

@BethanyG - Thanks for your detailed response.

It looks like #1976 in problem-specs already addresses the math issue, unless you believe more clarification is still needed. Should I still add my recommendation to this issue?

[BethanyG]

@KaiAragaki -- 🤔 I .. somehow didn't track that Sascha made adjustments to the description text already.

Maybe in that case we both close # 1791, and open a new issue in problem-specs with your recommendations? Unless you think they'd be better as a Python-only addendum. Does that make sense?

[github-actions]

This issue has been automatically marked as abandoned 🏚 because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.