Good Practices for IT Researchers: How to Make Our Code Accessible and Impactful?
Throughout my PhD journey, I’ve faced challenges in understanding others’ work and making my own research more accessible for others to build upon. One question I frequently hear from audiences is, “Do you share your code publicly?”
This recurring query highlights the growing importance of open and accessible research especially in IT field.
Example of good code repository: https://github.com/Newbeeer/Poisson_flow
1) Share Code on GitHub
The first step in ensuring accessibility is to host your code on platforms like GitHub. It allows us to:
- Collaborate: Share your work with co-researchers, allowing contributions and discussions.
- Version Control: Keep track of changes in your codebase.
- Visibility: Enable other researchers to find and utilise your work.
2) Include Essential Components for Easier Starting
The code repository should empower others to quickly understand and use our project.
a. README.md File
This is your project’s landing page and should answer these key questions:
What does your project do?
Why is it important? (Brief explanation of the problem it addresses)
How can someone use it? (Basic instructions to get started)
b. Installation Instructions
Provide clear steps to set up the environment:
Required dependencies (e.g., Python packages, libraries)
Command-line instructions for installation
Optional: Provide a requirements.txt file or a setup.py script for Python projects.
c. Input and Output Descriptions
Explain:
The expected format of the input (e.g., datasets, configurations).
The structure and meaning of the output (e.g., accuracy scores, predictions).
d. Examples
Add runnable examples in a notebook (e.g., Jupyter Notebook) or script:
Example datasets
Sample code snippets
Expected outputs for quick verification
e. License
Include a license file to clarify how others can use your code (e.g., MIT, Apache, or GPL). This is critical to enable legal reuse.
3) Provide a Reproducibility Script
Create a script (e.g., run_experiment.py) that allows users to reproduce the key results with a single command. This script should:
Load required data
Set up the environment
Run your main code
Save and display outputs
Final Thoughts
By making our code accessible and easy to use, we do more than share our research — that might encourage others to adopt it for model comparison, and perhaps even use it as a foundation for further development.
I think research work doesn’t end with a publication; it gains true value when it becomes a stepping stone for future innovation.
