Coherence and bug fixes

[alex-westwood]

Description

Please include a summary of the changes.

Troubleshooting section added to README and exercise instructions
Refactor RAP exercises and add a comment to highlight example outputs
Move function documentation in exercise solutions
Ensure wording is consistent across all the exercises

Type of change

You can delete options that are not relevant.

• Bug fix - non-breaking change
• New feature - non-breaking change
• Breaking change - backwards incompatible change, changes expected behaviour
• Non-user facing change, structural change, dev functionality, docs ...

Checklist:

• I have performed a self-review of my own code.
• I have commented my code appropriately, focusing on explaining my design decisions (explain why, not how).
• I have made corresponding changes to the documentation (comments, docstring, etc.. )
• I have added tests that prove my fix is effective or that my feature works (see here for more information).
• New and existing unit tests pass locally with my changes.
• I have updated the changelog.
• I have checked the pipeline runs with test data.

Peer review

Any new code includes all the following:

• Documentation: docstrings, comments have been added/ updated.
• Style guidelines: New code conforms to the project's contribution guidelines.
• Functionality: The code works fully implements the requirements and works as expected, handles expected edge cases, exceptions are handled appropriately.
• Complexity: The code is not overly complex, logic has been split into appropriately sized functions, etc..
• Test coverage: Unit tests cover essential functions for a reasonable range of inputs and conditions. Added and existing tests pass on my machine.

Review comments

Suggestions should be tailored to the code that you are reviewing. Provide context.
Be critical and clear, but not mean. Ask questions and set actions.

These might include:

• bugs that need fixing (does it work as expected? and does it work with other code
  that it is likely to interact with?)
• alternative methods (could it be written more efficiently or with more clarity?)
• documentation improvements (does the documentation reflect how the code actually works?)
• additional tests that should be implemented
  • Do the tests effectively assure that it
    works correctly? Are there additional edge cases/ negative tests to be considered?
• code style improvements (could the code be written more clearly?)

Further reading: code review best practices