As researchers, we all use code in our work. Often we will create new scripts or pieces of software, or modify code from someone else.
This repository contains materials and instructions for running a workshop for researchers focussed on giving them a basic introduction to two of the main techniques that will help them to improve their software: working with repositories and making code more maintainable. It covers how to choose and use a version control system for your source code and data, choosing a license for your software, why and how you deposit software in a digital repository, structuring your code to make it cleaner, and finding problems in your software. This is a subset of practices covered in the paper Good Enough Practices in Scientific Computing by Wilson et al.
- Introductions (15 minutes)
- Identifying good practice (15 minutes)
- Discussion of good practice (20 minutes)
- Good enough practices (20 minutes)
- Code review exercise (45 minutes)
- Code review summary (15 minutes)
- Introduction to version control (15 minutes)
- Choosing a license (5 minutes)
- Getting an ORCID (5 minutes)
- Software in repositories (15 minutes)
- Other topics (15 minutes)
- Wrap-up (10 minutes) are
This workshop does not require you to have a laptop, though some exercises and topics will benefit from being able to use the internet. Whilst the code review exercise will be on a piece of Python code, you should not need to understand python to complete it.
The slides for this workshop and handouts for the code review exercise are at: https://github.com/softwaresaved/clean-code-workshop/tree/master/materials
The code snippets for the code review exercise are at: https://github.com/softwaresaved/clean-code-workshop/tree/master/code_review
If you want to try the Jupyter Notebook version
of the sum of powers code, click on this icon:
You are encouraged not to look at the code review materials before you have done the exercises.
The materials in this repository are licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.
This means you are free to:
- Share — copy and redistribute the material in any medium or format
- Adapt — remix, transform, and build upon the material for any purpose, even commercially.
Under the following terms:
- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
The recommended citation is:
"Crash course on clean code for researchers" by Neil Chue Hong for the Software Sustainability Institute is licensed under CC BY 4.0
Please note that XKCD cartoons are licensed under CC-BY-NC, and PhD Comics are reproduced with permission of the author. New permission must be sought if modifications are made that change the use of these images.
This work was support by EPSRC/ESRC/BBSRC grant EP/N006410/1 for the UK Software Sustainability Institute. It was originally developed for the NIOO and DANS workshop on Open Science Tools, Data & Technologies for Efficient Ecological & Evolutionary Research which ran on the 7/8 December 2017.
It is based on the practices covered in the paper Good Enough Practices in Scientific Computing by Wilson et al and materials from Mike Jackson's GRADnet training course.