Repository navigation
Self Learning: Software Development
The project design guide from the Turing way project provides best practices and guidance for the planning and development aspects of a research software project.
Collaborative software development on GitHub/GitLab to release the software can benefit from a structured approach.
Several git branching models and strategies are used in research software development. To choose a branching model that is suitable for your project, the following considerations need to be discussed:
- How many people are contributing to the code base?
- How frequently do you plan to release a new version of the software?
- How long would you like to maintain and support the older versions of the software?
For larger projects that require a structured (and more strict) approach that reduces conflicts and improves maintainability, we would recommend adopting GitFlow. For smaller projects with fewer contributors, the suggested model from GitHub will be sufficient.
- Code Refinery – Branch design lesson
Adopting a branching method is part of a broader effort to improve collaborative software development. We include the following references to improve software collaboration:
- The Turing Way – Guide for Collaboration
- Code Refinery – Collaborative distributed version control
- Include a clear contributing guidelines document in the repository Consider implementing a team member lifecyle to facilitate the on- and off-boarding (temporary) team members
Sphinx is the most popular platform for creating documentation for Python projects. Recommendations for Python code documentation:
- Sphinx tutorial – Getting started
- Code Refinery – Code documentation with Sphinx
- Creating automatic API references from Python docstrings
- We recommend using the Numpydoc style formatting of the docstring
- General documentation guidelines for open source software
- Self-paced publicly available intermediate level training courses on tips and techniques for python code development and maintenance: Research software engineering with Python and Intermediate Research Software Development in Python
- Manage software dependencies by using a requirements.txt (pip) or environment.yml (conda) file in your project, this would ensure that your software is reproducible by others. Continuous Integration
- Test design concepts and examples from Code Refinery
- Follow a coding style/standard to ensure consistency in code development for a project that involves multiple developers. For Python, use the PEP8 coding style guidelines.
- Code quality: Use flake8 (static code analysis tool) to check the code against the PEP8 coding standard. Use black to format the code as per PEP8 coding standard. Use pylint to detect code smells and to get suggestions for code refactoring.
The references below provide guidelines to make your code FAIR (Findable, Accessible, Interoperable and Reusable) and ready for publishing.
- TU Delft – Open Science
- Five recommendations for FAIR (Findable, Accessible, Interoperable, Reusable) software
- Utrecht University – Best practices in Writing Reproducible code
- TU Delft – Guidelines on Research Software
- TU Delft - Open Science Community
- Software Carpentry - Sign up for the software carpentry workshop (free of cost) at TU Delft
- Code Refinery - Sign up