Adding more tips for good script documentation and organization in "Intro to R"

[jaxinewolfe]

Hello R ecology lesson maintainers! I have a small suggestion for the Intro to R lesson which you may take or leave as you see fit :)

That is, I think the sections on "Saving your script" and "Comments" would benefit from an addition/expansion to include good practices in script documentation and organization. For example, at the beginning of each new script, I like to encourage learners to form the habit of including information about the script itself. This usually includes: title, authorship, corresponding author's email, and a brief description of what the script does. In this way, every script they write/contribute to will have basic documentation and attribution. Additionally, if the script is shared with someone who did not develop it, they will be able to send clarifying inquiries directly to the corresponding author.

I'd also like to note that I have found it helpful to introduce code sections as a good tool for script organization and navigability. In workshops, I find that this also serves to visually orient learners to which section of a lesson that is being covered (ex. # Prepare Workspace ####....# Creating objects in R ####....).

[sspeir]

I agree! Annotation is such an essential "best practice" for coding. I think that information could be added as to how to annotate code effectively. I learned this lesson the hard way decently far into my coding experience, when trying to return to old code and having no idea what I did. I think it could be a very basic intro to the importance of the topic, but a critical component to cover nonetheless!

[nickaplan]

I appreciate the link provided on code sections. This is new to me. A simple suggestion I will add is to use four has tags before and after your comment, which will create a table of contents or outline for organizing your code quickly. I find the table of contents/outline helpful when going back to code snippets I've created in coursework, such as The Carpentries, or in a longer script that includes many sequential steps. Also, I may outline my steps first, and then fill in the contents as I work - sometimes from day to day, so I can see where I left off. Lastly, if there is a step, which requires input from a colleague, I can quickly directly them to it. This is a quick means for organized and annotated code, which could be added as a tip. For example:

1.0 import packages, set working directory and read in csv

2.0 look at the structure of the data, as well as the first 6 rows

3.0 next,

Then, by clicking the outline icon you can see the Table of Contents (see attached jpeg), which are essentially the steps followed.

[tobyhodges]

Thanks everyone for contributing to this discussion. The lesson underwent a major update and reorganisation when https://github.com/datacarpentry/R-ecology-lesson/pull/887 was merged. As this issue relates to content in a version of the lesson before that update took place, I will close it. Please open a new issue if you believe that some or all of the changes being discussed here remain relevant to the redesigned lesson, linking to this thread where appropriate.