[Kindergarten Garden] Making instructions clearer

[astrieanna]

I would like to be able to complete this exercise by reading the instructions without examining the tests. This is not currently possible because the instructions do not define the interface that the Garden class is expected to implement.

From completing the exercise, I believe that the interface is:

• A constructor that takes one positional argument and one optional argument. The positional argument is the two rows of plant initials; the optional argument is a list of student names.
  • When no argument is passed, the student names should be the 12 names from these instructions.
• A plants method that takes a positional argument : a student's name. This should return a list of strings, where each string is the full name of a plant the student planted. The plant names should be left-to-right with the plants in the row closest to the window listed first.

I realize that most of the details of plants return value appear in the instructions already, but the instructions never mention that there's a function plants that is returning these values, nor does it mention that some tests will construct a garden by passing in a new list of students.

I was confused that the stub code in the editor when you start this exercise has students as a positional argument to the constructor, when the first 17/19 tests do not pass in a list of students.

This information could instead be added in docstrings in the initial code provided, but I don't know how much stub code is allowed when this is a practice exercise rather than a new concept.

I'm happy to make the edits required to improve this exercise, if there are changes that would be welcome.

[github-actions[bot]]

🤖   🤖

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][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. 🌈 ✨

[BethanyG]

Hi @astrieanna 👋🏽

Thanks for this issue, and for the offer to re-work the instructions. A few things to note:

1. By design, the practice exercises (the exercises that are not in the syllabus tree as the "main" exercises in the boxes) are implemented as a form of TDD - Test-Driven development~searchTerm~'~sort~false~sortDirection~'asc~page~1)). But in exercism's case, we've written out the basic tests for you ahead of time. TL;DR - the expectation is that you engage with and look at the tests in addition to the instructions/specification. That doesn't mean we can't do better on the instructions. But it does mean that we will probably never get to the point of specifying everything in detail -- because we expect you to explore the test file.

2. Practice exercises are intended to be as open-ended as possible, and to encourage discussion with a mentor. That means we take pains to not dictate implementation. Now for OOP exercises in OOP-supporting languages, some exercises do indeed "dictate" a class and/or method names. But apart from importing expected class and or method names, we try not to overly constrict a student to a particular interface. We strive to have the tests look for results -- I don't care how you implemented Garden -- I care that when I call garden.plants("Alice"), I get back a list that has ["Violets", "Clover", "Radishes", "Clover"]. Even the parameters listed in the stub are optional -- you could call them anything you like. And for students, many community solutions use a default argument of None, rather than use it as positional-only. Again, this is meant to encourage a conversation with a mentor about different possible approaches or techniques.

3. Stub code for practice exercises is kept to a minimum. While we have been discussing if more detail is warranted, we have been wary of over-specifying or constricting implementation. For now, we are going with bare minimum sans docstrings or typehinting. We might revisit that later this year.

4. Problem descriptions for practice exercises are actually cross-track and are maintained in a repo called problem-specifications. The reason that some problems may feel ... vague ... is that they're specified for more than one programming language. So the specifics of wether Garden is a class or a function or ... something else .... is left to the track. Which brings us to ....

5. If you want to add track-specific detail to the instructions for a practice exercise, you need to make an instructions.append file. Here is an example from the Clock exercise that details the difference between __str__ and __repr__. I could imagine something similar for Kindergarten Garden that added some more information or hints on classes, default arguments, constructors and maybe even class attributes -- and maybe also mentioned that the plants method returns a list. And I'd be happy to review an append. Just keep in mind that you don't want to over-specify.

I hope that addresses your concerns. And again -- happy to entertain an instructions.append. Conversely, you could also open and issue in problem-specifications and discuss there with track maintainers what additional information in the general problem description would be helpful.

[BethanyG]

Hi @astrieanna -- are you still interested in working on an instructions.append for this exercise, or should we close it for now? Please let me know! 😄 Thanks.

[astrieanna]

Yes, I'm interested. Thank you for the thorough and quick response. Sorry, I had a busy week and didn't get back to this.

I'll submit a PR for the instructions.append in the next few days.

[BethanyG]

Thrilled you want to take it on! 🌟 Just as a bump (that answer above was ... long 😉 ), here are several instruction.append file examples:

1. Clock
2. Affine Cipher
3. High Scores

And the (obligatory) documentation links 😄 :

• Instructions Append
• Writing Style Guide
• Markdown Specs

Additionally, if needed, you can add a hints.md file with task-by-taks hints to help students who are stuck. Thinking this might be a good way to address some of the frustrations you outlined with interface design. Could be a nice place to put links in for the different types of parameters, etc.:

Hints.md for Practice Exercises

[BethanyG]

Now that #2915 has been merged, I am going to close this issue. Nice work, @astrieanna!