guides_and_good_practices.rst

Guides and good practices

This page contains further resources on various topics ranging from good coding practices to reproducible research. It is meant as a reference, not as something you should read from start to end. Just pick a topic you are interested in or that you need right now and start reading.

Site contents

• Good coding practices
• Code documentation
• Git and GitHub
• Research software engineering
• Open Science and reproducible research
• FAIR software

Good coding practices

• PEP 20: The Zen of Python.
• PEP 8: Style Guide for Python Code.
• Python Naming Convention.

Code documentation

• PEP 257: Docstring Conventions.
• |NumPy_docstring_convention|.
• Benjamin D. Lee, "Ten Simple Rules for Documenting Scientific Software", PLOS Computational Biology, 2018, 14, e1006561.
• A beginner's guide to writing documentation.

Git and GitHub

• Pro Git book: The standard book about Git. If you are new to Git, the first three chapters give you a very good idea about what Git is and how to use it.

• Learn Git Branching in an educational game.

• GitHub Quickstart.

• GitHub Training:

  • Introduction to GitHub.
  • Communicating using Markdown.
  • Reviewing pull requests.
  • Managing merge conflicts.
  • Create an open source program.
  • GitHub Actions - Hello World.
  • GitHub Actions - Continuous Integration.

Research software engineering

• Greg Wilson, D. A. Aruliah, C. Titus Brown, Neil P. Chue Hong, Matt Davis, Richard T. Guy, Steven H. D. Haddock, Kathryn D. Huff, Ian M. Mitchell, Mark D. Plumbley, Ben Waugh, Ethan P. White, Paul Wilson, "Best Practices for Scientific Computing", PLOS Biology, 2014, 12, e1001745.
• The Zen of Scientific Computing (Scientific Computing Department of Aalto University, Finland).
• SciPy Lecture Notes: One document to learn numerics, science, and data with Python.
• Research Software Engineering with Python (The Alan Turing Institute, UK).
• Lessons and tutorials of CodeRefinery on various topics like version control, code testing, modular code development and many more.
• Workshop Materials of the Helmholtz Federated IT Services (HIFIS) on Git, GitLab, code testing with pytest and other research software engineering topics.

Open Science and reproducible research

• Florian Markowetz, "Five selfish reasons to work reproducibly", Genome Biology, 2015, 16, 274.
• Geir Kjetil Sandve, Anton Nekrutenko, James Taylor, Eivind Hovig, "Ten Simple Rules for Reproducible Computational Research", PLOS Computational Biology, 2013, 9, 1-4, e1003285.
• The Turing Way: Handbook to reproducible, ethical and collaborative data science containing a lot of in-depth guides from project design over data management and research software engineering to collaboration and communication (DOI: 10.5281/zenodo.3233853).
• Open Science Training Handbook: A European projekt to guide teachers/lecturers that want to include Open Science aspects in their teaching (DOI: 10.5281/zenodo.1212495).
• Recommendations on the development, use and provision of Research Software: A position paper of the Alliance of German Science Organisations (DOI: 10.5281/zenodo.1172987).

FAIR software

The following papers provide suggestions how to extend the FAIR principles (Findable, Accessible, Interoperable, Reusable) that are already established for research data to research software:

• Anna-Lena Lamprecht, Leyla Garcia, Mateusz Kuzak, Carlos Martinez, Ricardo Arcila, Eva Martin Del Pico, Victoria Dominguez Del Angel, Stephanie van de Sandt, Jon Ison, Paula Andrea Martinez, Peter McQuilton, Alfonso Valencia, Jennifer Harrow, Fotis Psomopoulos, Josep Ll. Gelpi, Neil Chue Hong, Carole Goble, Salvador Capella-Gutierrez, "Towards FAIR Principles For Research Software", Data Science, 2020, 3, 37-59.
• Daniel S. Katz, Morane Gruenpeter, Tom Honeyman, "Taking a Fresh Look at FAIR for Research Software", Patterns, 2021, 2, 100222.