This is what I wrote students in Jan 2024 after seeing their reports from HS2023 and this clarification should be added to the website for next time this course is run:
How much code to show in the report? This is a taste question, but relegating contents to external scripts can come at the cost of transparency. You should therefore put additional effort in describing where what object is created. In grading your reports, I came to realise that I prefer to see all relevant steps (code) in the report. Contents relegated to external scripts should be steps that are not of direct interest to answering the question at hand or demonstrating a certain workflow. For example, downloading and pre-processing the data can easily be done in an external script. Try also to relegate functions into external files. To clarify what goes into a function and what goes into a script, consider:
A function should implement a single step of the workflow.
A function should be used/called multiple times within the workflow. If it’s called only once, it belongs into a script or kept in the report itself.
A function should not specify or construct a file path.
Data download from external sources typically goes into a script, stored in analysis/.
If in doubt, keep code in the report and add the option to show/hide code and default hide it.
In the future, we’ll explain the format of a report as being something like a blog where a workflow for a specific task is explained with text and code. The code should be simplified down to the essentials.
This is what I wrote students in Jan 2024 after seeing their reports from HS2023 and this clarification should be added to the website for next time this course is run:
How much code to show in the report? This is a taste question, but relegating contents to external scripts can come at the cost of transparency. You should therefore put additional effort in describing where what object is created. In grading your reports, I came to realise that I prefer to see all relevant steps (code) in the report. Contents relegated to external scripts should be steps that are not of direct interest to answering the question at hand or demonstrating a certain workflow. For example, downloading and pre-processing the data can easily be done in an external script. Try also to relegate functions into external files. To clarify what goes into a function and what goes into a script, consider: