How should you provide adequate documentation with your code to make it understandable for reusers?
In-code documentation
README
A README file is a text file that provides information about an open source software project, including details on how to install and use the software, as well as any dependencies or prerequisites that are required. A README file is often the first thing that users will see when they encounter an open source project, and it is an important tool for helping users understand and use the software.
A README file should contain the following information:
A brief overview of the project, including its purpose and main features.
Installation/usage instructions, including any dependencies or prerequisites that are required.
License information
Recommended citation (see Software Citation)
When the software is a bigger or on-going project, also include the following information:
Contributing guidelines, if the project is open to contributions from the community.
A list of any known issues or bugs, along with any workarounds or fixes that are available.
Contact information for the project maintainers or developers, in case users have questions or need support.
README video by Barbara Vreede
examples:
A template to make good README.md
CodeMeta creates a minimal metadata schema for research software and code.
Reusable code
- List dependencies/variables on top
- Using a ‘main’ code calling other codes to make it more readable
- Add in comments at the start about what the code does, and what in/outputs are expected
- Use functions
- Make tests for the functions
