rse-sheffield/software_engineering_best_practices

The course notes for the Best practices in software engineering course at the University of Sheffield.

To contribute changes, please follow these steps:

1. Fork this repository
2. Clone your forked repository locally
3. Activate the environment: :: conda env create -f environment.yml conda activate sebp
4. Launch Jupyter Lab or Jupyter notebook to modify the notebook files
5. Commit changes and push
6. Submit merge request from your fork

software_engineering_best_practices's Issues

Make slides look pretty

Development Environment

Currently Jupyterlab is suggested. Do we want to advocate something else? Colab? VScode? Pycharm? How big a part of this should be setting up a development environment?

University of Bristol advice should perhaps be removed

Need to check if any Bristol specific stuff needs to be replaced with TUoS, or removed.

Delivery plan

Assign

• Introduction
• Introduction
• Licensing
• Testing
• Summary

Make setup a separate section

Typehints

More signposting for version control/git/github training

This training concerns best practices in software engineering but (perhaps rightly) it's only mention of version control with git is at the very end.

I think that this could do with signposting at the beginning and end of the material since it's such a core concept in best practice for software engineering, but is of course too big a concept to squeeze into the half day course.

Error handling

Motivation for testing

Some slides to introduce and explain motivation for testing to be delivered before the learners start on the testing bit.

Repository structures

We could introduce basic repo structures, e.g. where to keep code, data, tests etc so that they can be easily packaged at a later date

Dependency management and packaging

A can, open.
Worms, everywhere.

Virtual Environments

Adapt CI for GH actions

Remove/modify some failing links to Matt's intermediate python course

e.g. /intermediate_python/Exceptions.html

Test case - code repetition

I find that a lot of cases have the same code to setup as the code that appears in other cases, what's the best practice for this?

Self-led? Timings? Structure?

Is the self-led approach here OK? Should we move it to live-coding? Should we have little check-ins after each "module"? I think, yes.

Motivation for documentation

Could just be covered verbally, but I think there is good, research-relevant motivation for testing and licensing but there is perhaps some missing motivation for "why should I, as a researcher, write docstrings?"

"Licensing" should be delivered as slides

https://milliams.com/courses/software_engineering_best_practices/Licensing.html

Think about environment setup

The setup suggests using anaconda navigator to implement JupyterLab, which gets everyone who uses it into a visually similar environment, it presents a problem I've come across:

• when running !python ... from the jupyter/ipython console, it uses one python installation
• when opening a terminal, inside jupyterlab, it opens (at the home directory) using whatever the system default is.

We had a participant today who found that it opened in the conda base env, which was using python 2.7. This meant that a LOT of things ran in an unexpected way. We might consider spending some more time establishing this at the start.

Cut sections 4 and 5?

Or offer as "stretch goals"?

Consider using Binder

We can use binder to build a JupyterHub for the full repo:

https://mybinder.org/v2/gh/RSE-Sheffield/software_engineering_best_practices/714d5aefe52b0143e96b3325a48727f266cf00fe

Can also use a pretty button:

We can then link back to the repo for those that want to install on their own machine using conda

add some links for ci/cd configs/solutions

eg github actions, gitlab whatevers

Readthedocs

Should we signpost readthedocs?

Write intro slides

Make "index" slide that links to all the other slides and bits of the course