[Practice Exercises] Add Guidance for Exercises that Require Raising Errors or Error handling

[BethanyG]

When we transitioned to the current version of exercism, we removed the generic "raising exceptions" notices from all the exercise READMEs. We felt they were adding confusion and leading students to insert error raising and handling in places where they should not have been inserting it.

For the Python track, we were (and are!) planning error handling concept exercises to help students learn how to raise and handle errors properly in their code.

But those exercises are still in process, and we have 42 practice exercises that test for error handling in one way or another.
37 of these include JinJa2 test generation templates.

As a stopgap while we create the error handling concept exercises, we need to create practice exercise .docs/instructions.append.md files for the 42 exercises that add back a blurb about how to raise an exception. The original vs proposed language for the instructions.append.md is at the bottom, but is open to any edits that make sense and help student understanding.

For the 37 JinJa2 exercises, we will need to modify the test generation templates to test for a meaningful exception message, and not just the presence of any exception. We'll then need to regenerate those test files.

For the 5 exercises that remain, we will need to hand-edit the test files as opposed to editing a generation template.

Recommend that a PR for ONE exercise be done as a first pass to make sure the changes do indeed makes sense, then the remainder of them can be done.

• Practice Exercise Specs
• Exercism Markdown Specs
• Python Track Test Generator
• JinJa2 Tutorial

These are the 42 practice exercises in question:

PR 2685

• [x] affine-cipher | test file | template file
• [x] all-your-base | test file | template file
• [x] bank-account | test file
• [x] binary-search | test file | template file
• [x] binary | test file

PR 2691

• [x] bowling | test file | template file
• [x] change | test file | template file
• [x] circular-buffer | test file | template file
• [x] collatz-conjecture | test file | template file
• [x] dot-dsl | test file

PR 2692

• [x] error-handling | test file Exercise has been depreciated.
• [x] forth | test file | template file
• [x] go-counting | test file | template file
• [x] grains | test file | template file
• [x] hamming | test file | template file

PR 2715

• [x] hangman | test file
• [x] hexadecimal | test file Exercise has been depreciated.
• [x] largest-series-product | test file | template file
• [x] meetup | test file | template file
• [x] minesweeper | test file | template file

PR 2716

• [x] nth-prime | test file | template file
• [x] nucleotide-count | test file Exercise has been depreciated.
• [x] ocr-numbers | test file | template file
• [x] octal | test file Exercise has been deprciated.
• [x] palindrome-products | test file | template file

PR 2725

• [x] perfect-numbers | test file | template file
• [x] phone-number | test file | template file
• [x] pov | test file
• [x] queen-attack | test file | template file

PR 2727

• [x] rational-numbers | test file | template file actually, no error cases here.
• [x] robot-simulator | test file | template file No error cases currently. Consider adding some later.
• [x] roman-numerals | test file | template file Doesn't have error cases either. Maybe we should consider adding some.
• [x] run-length-encoding | test file | template file No error cases.
• [x] saddle-points | test file | template file
• [x] satellite | test file | template file

PR 2734

• [x] say | test file | template file
• [x] series | test file | template file
• [x] sgf-parsing | test file | template file
• [x] simple-linked-list | test file
• [x] tree-building | test file
• [x] variable-length-quantity | test file | template file
• [x] wordy | test file | template file

  ---

  The original and proposed new error handling messages are below.

[ORIGINAL]

Exception messages

Sometimes it is necessary to raise an exception. When you do this, you should include a meaningful error message to indicate what the source of the error is. This makes your code more readable and helps significantly with debugging. Not every exercise will require you to raise an exception, but for those that do, the tests will only pass if you include a message.

To raise a message with an exception, just write it as an argument to the exception type. For example, instead of raise Exception, you should write:

raise Exception("Meaningful message indicating the source of the error")

---

[Suggested Changes]

Exception messages

Sometimes it is necessary to raise an exception. When you do this, you should always include a meaningful error message to indicate what the source of the error is. This makes your code more readable and helps significantly with debugging. For situations where you know that the error source will be a certain type, you can choose to rase one of the built in error types, but should still include a meaningful message.

This particular exercise requires that you use the raise statement to "throw" an exception. The tests will only pass if you both raise the exception and include a message with it.

To raise an exception with a message, write the message as an argument to the exception type:

raise Exception("Meaningful message indicating the source of the error")

[github-actions[bot]]

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.

[BethanyG]

I can only hope to abandon this. Nice try, gitbot, but I think this needs to stay open. 😞

[BethanyG]

Related website issue that might prevent these from showing right away: https://github.com/exercism/exercism/issues/6063. Should be fixed soon (probably before these are all done).