.. _guides-and-good-practices-label: 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. .. contents:: Site contents :depth: 2 :local: 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 Skills`_: - `Introduction to GitHub`_. - `Communicate using Markdown`_. - `Review pull requests`_. - `Resolve merge conflicts`_. - `Hello 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. .. _Python Naming Convention: https://github.com/naming-convention/naming-convention-guides/tree/master/python .. _The Zen of Scientific Computing: https://scicomp.aalto.fi/scicomp/zen-of-scicomp/ .. _SciPy Lecture Notes: https://scipy-lectures.org/ .. _Research Software Engineering with Python: https://alan-turing-institute.github.io/rse-course/html/index.html .. _CodeRefinery: https://coderefinery.org/lessons/ .. _Workshop Materials: https://gitlab.com/hifis/hifis-workshops .. _Pro Git book: https://git-scm.com/book/en/v2 .. _Learn Git Branching: https://learngitbranching.js.org/ .. _GitHub Quickstart: https://docs.github.com/en/get-started/quickstart .. _GitHub Skills: https://skills.github.com/ .. _Introduction to GitHub: https://github.com/skills/introduction-to-github .. _Communicate using Markdown: https://github.com/skills/communicate-using-markdown .. _Review pull requests: https://github.com/skills/review-pull-requests .. _Resolve merge conflicts: https://github.com/skills/resolve-merge-conflicts .. _Hello GitHub Actions: https://github.com/skills/hello-github-actions .. _Continuous Integration: https://github.com/skills/test-with-actions .. _The Turing Way: https://the-turing-way.netlify.app/index.html .. _Open Science Training Handbook: https://open-science-training-handbook.gitbook.io/book/