Software produced by the lab
The following are guidelines to be followed when producing software tools as part of your work at the lab.
Licensing
- We value respect for licensing terms and ensuring that we comply with them at all times.
- All code generated in the lab should be open-source with a permissive (non-copyleft) license (MIT, BSD, etc).
- Our preferred license is BSD 3-clause.
- If contributions to upstream copyleft (GPL, etc) projects are made, those contributions can be licensed in accordance with the upstream project license.
- For further discussion see Stodden (2008).
Project leadership
- When software is developed as a result of funded activity, the leadership directions will be set collaboratively during the proposal writing process and between lab members and Leo.
- For externally developed projects, leadership is as decided by the broader community.
- Decisions regarding strategic direction for software projects (including algorithmic strategies) will be made collaboratively.
- For technical directions on lab-developed software, we operate by “lazy consensus”.
External projects
- We strive to be good “citizens” of the broader open-source community.
- We encourage lab members to contribute upstream to open-source projects.
- Projects developed with external collaborators (e.g., Fatiando a Terra) should have their discussions held openly. This can help discourage the notion that projects developed by lab members are not community projects.
- For more discussion about this topic, see Matt Turk’s paper Scaling a Code in the Human Dimension.
Languages
- Use Python for most software.
- Experimenting with Julia and other languages is acceptable and even desirable.
- For code that needs to be optimized, the first preference is (in order): Numba, then Cython, and finally C.
Coding standards
- Code should avoid being “too clever”, for example clever abuses of languages and algorithms that cut corners in the interest of marginal time savings.
- Clarity and maintainability take precedence over performance to ensure that the code can remain useful beyond the original scope of the project.
- Tests should be considered mandatory for new functionality and bug fixes. These tests should be part of automated testing suites.
- Use black to automatically format Python code.
- Documentation must be added with any new code and should be accessible to newcomers. Include examples whenever possible.
- Comments (not including markdown cells in notebooks) are encouraged but not necessary. Code should be as self-describing as possible. Where complexity is inevitable, comments should allow anyone to understand the shortcuts and reasoning.
- Include citations to algorithms whenever possible, including links to online resources.
- Docstrings should be added to all functions and classes in Python code.