What Transforms Project-Specific Code into Sustainable Scientific Software? Principles for Developing Reusable Open-Source Research Tools

1. Introduction

Computational research increasingly depends on code that is written inside research projects rather than by dedicated software teams. A researcher may load a dataset, apply transformations, run an analysis, save figures, and use the output to support a scientific claim. In that original setting, the code may be entirely fit for purpose. The developer knows the folder structure, local parameters, implicit assumptions, software environment, and unresolved limitations of the analysis. The status of such code changes, however, when it becomes part of the scientific record. It may be reused for a follow-up study, adapted by a collaborator, published as supplementary material, released as a package, cited in a paper, or inspected by a reviewer. At that point, the question is no longer only whether the code once produced the expected output on one computer, but whether other people can understand, install, run, validate, modify, cite, and maintain the computational work.

These concerns are not new. Best-practice guidelines for scientific computing have emphasized version control, readable code, automated testing, documentation, and reproducible workflows for more than a decade [1,2,3]. Open development practices, usable interfaces, documentation, and clean code have likewise been discussed as practical requirements for scientific software [4,5,6,7]. The FAIR principles established a shared vocabulary for findable, accessible, interoperable, and reusable research outputs [8], and have since been adapted explicitly to research software [9]. Software citation principles further clarify that software is a citable scholarly object and that developers deserve credit for software contributions [10]. Despite this literature, many computational projects still treat software sustainability as a final polishing step. Documentation is written after the analysis is finished. Tests are added only after bugs have affected users. Licensing is considered only when the repository is made public. Citation metadata is created after a release has already been shared. This ordering is understandable, especially in time-limited research projects, but it makes sustainability more expensive than it needs to be. We argue that project-specific analysis code becomes sustainable scientific software when reproducibility, reuse, documentation, testing, citation, and openness are built into the project as development practices. This does not mean that every exploratory notebook must immediately become a polished software package. It means that researchers can adopt a small set of practices that preserve computational context as a project grows. These practices are also recoverable, i.e., if they were not adopted early, they can be added later.

Here we propose seven principles for developing reusable open-source research tools. We focus on software that supports empirical or computational research rather than on commercial software products. The principles are intentionally general, as they apply to image analysis, data processing, simulation, statistical analysis, bioinformatics, neuroscience, and many other computational domains. The motivation for this perspective is practical. Sustainable research software lowers the effort required to reproduce analyses, reduces the risk of silent errors during reuse, makes computational decisions easier to review, and allows software contributions to be credited as scholarly work. For developers, these practices make projects easier to extend and maintain. For users, they make tools easier to evaluate and adopt. For research communities, they turn code from a fragile by-product of individual projects into shared infrastructure that can support cumulative, transparent, and reusable science. In this sense, sustainable software practices improve not only the software project itself, but also the scientific quality of the analyses, publications, and findings that depend on it.

2. Problem Description

A typical analysis script developed during an active research project reads files from a local directory, assumes a specific naming convention, applies several preprocessing steps, selects parameters that were optimized during exploration, creates a summary table, and exports figures. None of these steps is necessarily wrong. The problem is that much of the scientific context can remain encoded outside the script, i.e., in undocumented development decisions, local file paths, manual preprocessing choices, unrecorded package versions, or project-specific assumptions that were never written down. This creates several failure modes. First, the analysis may be difficult to reproduce because the required input structure, dependencies, and execution order are unclear. Second, it may be difficult to review because the relation between code, parameters, intermediate files, and published outputs is not explicit. Third, reuse may become risky because assumptions that were valid for the original dataset are silently carried into a new context. Fourth, software contributions may remain difficult to credit if there is no release, license, citation metadata, or persistent identifier. Finally, maintenance becomes fragile when a project depends on undocumented individual decisions rather than on visible project structure.

The scale of the problem is increasing because scientific software is now routinely published, archived, and linked to public code repositories. In an exploratory screening of GitHub-linked software records from the Journal of Open Source Software (JOSS) and Zenodo between 2016 and 2025, the number of distinct software records increased markedly over time, with Zenodo contributing a much larger archival volume and JOSS representing a smaller curated software-publication venue (Figure 1a). At the same time, repository activity differed strongly between the two sources. JOSS-linked projects showed substantially higher first-year commit activity than Zenodo-linked projects (Figure 1b), suggesting that reviewed software publications more often correspond to actively developed repositories. Issue activity was also consistently higher in the JOSS-linked cohort (Figure 1c), indicating more visible user feedback, maintenance, or support interactions. Pull-request activity showed a similar source-dependent pattern (Figure 1d), consistent with a greater degree of collaborative development in JOSS-linked repositories. These observations should not be interpreted as a ranking of platforms, as Zenodo and JOSS serve different roles. Rather, they illustrate that public release or archival deposition alone does not make software sustainable. Sustainability depends on visible development, documentation, testing, citation, and maintenance practices around the released code.

The resulting gap is practical rather than purely conceptual. Researchers have access to mature recommendations for reproducible computing, FAIR software, and software citation [1,2,3,9,10], but many projects lack a compact development model that connects these recommendations to the everyday transition from analysis script to reusable research tool. The central question therefore is which minimal development practices allow project-specific analysis code to become inspectable, reusable, testable, citable, and maintainable without imposing unnecessary engineering overhead.

3. From a Project-Specific Script to a Reusable Research Tool

The transition from a project-specific script to a reusable research tool is often misunderstood as a question of size. A short script is assumed to be informal, whereas a larger code base is assumed to be software. In practice, size is a poor criterion. A 50-line script can be reusable if it has a clear interface, documented assumptions, version history, tests for key behavior, and a license. A large repository can remain unsustainable if it lacks documentation, citation information, tests, releases, or a transparent development history. The relevant transition is therefore not from small to large, but from local project context to shared infrastructure. In a local project context, the original developer may rely on implicit knowledge and undocumented decisions. In shared infrastructure, assumptions must be externalized. Input formats, dependencies, parameter choices, expected outputs, limitations, validation steps, and contribution pathways must be visible somewhere other than in the personal knowledge of the original author.

For many research projects, the first step is not to create a package. It is to identify the boundary between exploratory work and reusable functionality. Exploratory work may remain in notebooks, prototypes, or analysis scripts. Reusable functionality should be separated into functions, modules, command-line tools, packages, or workflow steps that can be invoked consistently. This separation allows research exploration to remain flexible while preventing core computational logic from being copied, modified, and silently diverging across analyses.

The transition also changes the unit of scientific inspection. In a traditional experimental paper, readers inspect the method, data, figures, and conclusions. In computational research, the path from data to result is itself part of the method. If that path is encoded in software, then the software becomes part of the scientific object. It must therefore be preserved, described, and cited with comparable care.

4. Seven Principles for Sustainable Research Software

We propose seven principles that turn a project-specific script into sustainable research software. They are not independent checkboxes, their value comes from their combined effect, wheredru modular code can be tested, tested code can be refactored, documented code can be reused, released code can be cited, and transparent development allows users to understand how the project changes over time.

4.1. Modular Design

Modular design means that distinct computational responsibilities are represented by distinct parts of the project. A script that loads raw data, filters values, computes metrics, creates figures, writes outputs, and defines project paths in one continuous block is difficult to test or reuse because every step depends on the entire script. A modular project separates input/output, core calculations, configuration, visualization, and user interfaces. This does not require over-engineering. Even a small project can benefit from moving a repeated calculation into a named function with explicit inputs and outputs.

The purpose of modular design is not aesthetic, but to make assumptions visible. It also makes scientific validation more precise. If a segmentation algorithm, statistical model, or simulation step is implemented as a function with defined input and output types, that function can be tested independently. If the same computational logic is instead copied into several notebooks or scripts, small undocumented differences can accumulate, and it becomes unclear which implementation was validated, reused, or used to generate a particular result.

4.2. Version Control

Version control preserves the history of computational decisions. It records when a parameter changed, when a bug was fixed, which release generated a result, and how contributions entered the project. Git is a frequently used tool for version control, and platforms such as GitHub, GitLab, Codeberg, institutional GitLab instances, and Forgejo/Gitea hosts make Git-based collaboration visible (also see Table 1). Other version-control systems and archival workflows can also support controlled and inspectable project states, but the essential requirement is that changes are traceable and that specific versions can be recovered. Manual versioning through file names can be better than no versioning, but it is fragile and should not be the target state, as it does not capture why changes were made, how branches relate, or which exact state corresponds to a release. Version control is therefore not only a developer convenience, it is a reproducibility mechanism.

4.3. Automated Testing

Testing is often postponed in research software because the code is changing and the final analysis is not yet known. However, useful tests do not require complete stabilization of a project. They can initially focus on the computational behavior that scientific conclusions depend on, including file parsers, unit conversions, numerical formulas, data transformations, simulation steps, and expected outputs for small reference examples. Automated testing frameworks exist for most scientific languages, including pytest and unittest for Python, testthat for R, JUnit for Java, and built-in test frameworks for Julia and MATLAB. Continuous integration services such as GitHub Actions, GitLab CI, Codeberg/Forgejo-compatible runners, Jenkins, and institutional CI systems can run tests automatically when code changes. The goal is not to create a corporate engineering process, but to prevent silent changes in computational behavior.

4.4. Documentation

Documentation is the bridge between executable code and scientific method. A repository without documentation asks users to reverse-engineer assumptions from implementation details. Good documentation should state what the software does, what it does not do, how to install it, how to run a minimal example, what inputs and outputs are expected, which parameters matter, how results can be reproduced, how to cite the software, how to report problems, and how to contribute. It can be provided in several complementary formats, including a repository README, example notebooks, tutorials, API documentation, a wiki, a project website, Read the Docs, Quarto or Sphinx pages, package vignettes, or a methods paper. The appropriate combination depends on project maturity and audience. At minimum, the README should orient new users, installation instructions should support reproducibility, tutorials should demonstrate realistic workflows, API documentation should define reusable interfaces, and contribution guidelines should state how users can report issues or propose changes.

4.5. Public Availability and Open Licensing

Open licensing matters only if the code is available. Conversely, public code without a license is legally ambiguous because, by default, copyright restrictions still apply. Sustainable research software should therefore include both public availability and an explicit license.

Public availability usually means hosting source code in a repository platform such as GitHub, GitLab, Codeberg, an institutional GitLab, or another open forge. Archival platforms such as Zenodo can preserve release snapshots and assign digital object identifiers. Software Heritage can archive source code history. JOSS and similar venues can connect software to peer-reviewed software papers. Private cloud folders such as Google Drive, OneDrive, Dropbox, or Nextcloud may be useful for collaboration, but they are poor substitutes for public software release. They rarely provide transparent version history, issue tracking, release metadata, persistent citation, or clear contribution workflows.

License choice should reflect the goals of the project and institutional constraints (Table 2). Permissive licenses maximize downstream adoption, whereas copyleft licenses require derivatives to preserve openness under specified conditions. Documentation and data may require different licenses from source code. Researchers should check funder, institutional, and collaborator requirements before release.

4.6. Persistent Citation

Software citation gives credit and supports reproducibility. A publication that depends on a software release should cite that software in a way that identifies a specific version when possible. The FORCE11 software citation principles emphasize importance, credit, unique identification, persistence, accessibility, and specificity [10]. In practice, these principles can be supported by release DOIs through Zenodo or similar archives, CITATION.cff files, CodeMeta metadata, package registry metadata, software papers, and clear citation instructions in documentation. Persistent citation also helps maintain a distinction between the living repository and the version used for a particular scientific result. A repository may continue to evolve. A release archive should preserve the version that was used. This distinction is essential when software changes after publication.

4.7. Transparent Development

Transparent development means that users can see not only the current code, but also how the project changes. Public issue trackers, pull requests or merge requests, release notes, changelogs, roadmaps, contribution guidelines, deprecation policies, and tagged versions all help users understand the maturity and direction of a project. They also help developers by turning informal support requests into visible project knowledge. Transparency should not be confused with constant availability or unlimited maintenance. A small research group can state the expected level of support. A project can be transparent about being experimental, unmaintained, or maintained only for a specific use case. Such honesty is better than leaving users to infer maturity from silence.

5. What Changes When Code Becomes Shared

When code remains local to one project, correctness is often judged by whether it produces the expected output for the original analysis. When code becomes shared, correctness becomes broader. Users need to know whether the code behaves consistently across environments, whether installation steps are complete, whether error messages are informative, whether assumptions are documented, and whether limitations are visible.Several practical changes follow. First, implicit knowledge must become explicit. Folder structures, file naming conventions, unit choices, coordinate systems, preprocessing assumptions, and quality-control decisions should be written down. Second, reuse changes from copying fragments into the next analysis to importing, installing, or calling a maintained component. Third, validation becomes a project activity rather than an individual judgment. Tests, example datasets, reference outputs, and documented limitations allow others to check behavior without reconstructing undocumented development decisions.

The scientific object also expands. The result is no longer only a figure, table, or statistical value. The computational path to that result becomes part of the evidence. This is why software sustainability is not a cosmetic concern. It affects whether computational claims can be inspected and reused.

6. AI-assisted Coding and Scientific Accountability

AI-assisted and agentic coding tools can rapidly turn natural-language descriptions into functioning prototypes. This is a major opportunity for science. Researchers who are domain experts but not professional software engineers can create interfaces, tests, scripts, packages, and documentation faster than before. Empirical work on GitHub Copilot has reported substantial productivity gains in programming tasks [11], and recent guidance has begun to formulate rules for AI-assisted coding in science [12]. However, faster code generation does not automatically produce better scientific software. A generated package can still contain undocumented assumptions, untested behavior, hallucinated interfaces, security weaknesses, incompatible licenses, inaccessible dependencies, or plausible-looking but incorrect algorithms. Agentic tools may also generate more code than a project can realistically maintain. The core problem therefore changes from “Can we produce code?” to “Can we make the produced code scientifically accountable?”

The seven principles apply directly to AI-assisted projects. Modular design makes generated code reviewable in smaller units. Version control records which changes were introduced by humans or tools. Tests provide an external check on generated behavior. Documentation forces assumptions into prose and examples. Public availability and licensing clarify what has been released and under what terms. Persistent citation identifies the version used in a study. Transparent development allows users to inspect how AI-generated or AI-assisted code was reviewed, corrected, and maintained.

AI assistance can also help implement the principles themselves. Coding agents can draft tests, generate documentation skeletons, refactor scripts into modules, create continuous-integration configurations, or prepare citation files. These outputs still require human review and the scientific responsibility remains with the project authors. The easier it becomes to publish software-like artifacts, the more important it becomes to distinguish usable research infrastructure from unreviewed prototypes.

7. Research Software as Research Data Management Infrastructure

Research data management (RDM) is often described in terms of storage, metadata, repositories, and data sharing. These are essential, but incomplete for computational research. Data become scientific evidence through analysis, preprocessing, simulation, visualization, statistical modeling, and interpretation. These steps are often encoded in software. If the software is unavailable, undocumented, unversioned, uncitable, untested, or impossible to run, then data reuse may remain theoretical even when the dataset itself is accessible. Software sustainability is therefore a RDM topic because it preserves the executable context that connects raw data to scientific claims and allows this context to be inspected, reused, credited, and maintained. This view also aligns software with the FAIR principles. FAIR data require context that supports discovery and reuse [8]. FAIR research software extends these ideas to source code, executability, metadata, dependencies, and citation [9]. Sustainable research software turns research data into reusable evidence, not just stored files.

8. Example Application

To make the principles concrete, we consider a pseudo-code project named example_project. The project begins as a single analysis script that reads a local dataset, applies preprocessing, computes a quantitative summary, and exports a figure for one manuscript. The scientific aim is narrow, and the original script works for the original study. The question is how such a script can become a reusable research tool without turning into an unnecessarily large software project.

8.1. Start by Separating Reusable Logic from Project Context

The first step is to separate the reusable computational method from local analysis choices. A minimal modular structure might look like this:  

Structures like the one shown above do not require many files at the beginning. The important point is that core behavior lives in importable modules, while project-specific analyses can remain in a separate analysis/ or notebooks/ directory. The tool can then be used by the original manuscript and by future projects without copying code.

8.2. Write Functions with Explicit Inputs, Outputs, and Docstrings

Docstrings or similar structured documentation are not decoration, they state what a function assumes and is intended to do. A concise descriptive comment can make a scientific method easier to inspect than prose hidden in a separate methods paragraph.  

This example is intentionally ordinary. It shows three sustainability features: required inputs are explicit, the output is named rather than implicit, and invalid input fails early. Such small design decisions prevent many downstream ambiguities.

8.3. Add Tests Around Scientific Behavior

The first tests should cover behavior that matters scientifically. For pseudo-project, this could include correct handling of input formats, expected numerical summaries for a small reference dataset, missing-column errors, unit conversions, boundary cases, and reproducible outputs from deterministic processing steps. The goal is not exhaustive coverage at the beginning, but to make the most important assumptions executable.

Tests should be small enough to run often. A useful early pattern is to include a tiny synthetic or public example dataset and to test that the software produces the expected summary values from that dataset. Once tests exist, continuous integration can run them automatically on GitHub, GitLab, Codeberg/Forgejo-compatible infrastructure, Jenkins, or institutional runners. The test command should also be documented so that users can run the same checks locally.

8.4. Use Version Control and Continuous Integration

The project should be placed under version control before it is polished. As summarized in Table 1, the strongest default for most open research software is a distributed version-control system, usually Git, combined with a public or institutional repository host. Commits should be small enough to explain what changed, and tags should mark releases that correspond to manuscript analyses or public versions. Branches and pull requests or merge requests are useful because they connect discussion, review, and code changes, but the essential point is that the project history is inspectable.

Archival platforms in Table 1 play a complementary role. They preserve release snapshots and persistent identifiers, but they are not a substitute for an inspectable development history. Manual versioning through dated folders or copied files can be an emergency record, but it should be replaced by proper version control once the code supports scientific results or public reuse.

Continuous integration connects version control to testing. A repository can run tests automatically whenever code is pushed, reviewed, merged, or released. This can be implemented through GitHub Actions, GitLab CI, Jenkins, Woodpecker CI, institutional runners, or comparable systems. If no hosted automation is available, the project should still provide a documented local test command.

8.5. Document the Minimum Useful Context

A sustainable first documentation layer should include:

This list can be implemented gradually. A README can begin with overview, installation, quickstart, license, and citation. A documentation website can later add tutorials and API pages. The key is that users should not need to read source code to discover basic scientific assumptions.

8.6. Publish the Code and Choose a License

For public release, our example project could host its source repository on GitHub, GitLab, Codeberg, an institutional GitLab, or another forge. A release snapshot could be archived on Zenodo to obtain a DOI. The repository should contain a license file. It should not rely on a shared cloud folder as the primary publication venue.

Table 2 summarizes common license families and their typical implications for research software. Permissive licenses are often suitable when broad downstream adoption is the main goal, whereas copyleft licenses are useful when derivative works should preserve openness under specified conditions. Documentation, tutorials, figures, and example datasets may require separate licensing decisions because Creative Commons licenses are generally more appropriate for non-code artifacts than for source code. License lists maintained by the Open Source Initiative and SPDX provide standardized names and identifiers [13,14]. Practical license selection guides can help projects choose a license that fits their goals [15,16].

8.7. Make the Software Citable

The project should include a citation file, citation instructions in the README, and versioned releases. A release DOI through Zenodo or a similar archive can identify the exact version used in a manuscript [17]. Metadata formats such as Citation File Format and CodeMeta help repositories, archives, and citation tools interpret software metadata [18,19]. The citation should distinguish between the project and the version. A useful statement is: “If you use this software, cite version 1.2.0, DOI ..., and include the software version in your methods.” This small instruction can prevent ambiguity later.

8.8. Keep Development Transparent

Transparent development should make the state of the project legible to users and contributors. This includes visible issue tracking for bugs and feature requests, pull requests or merge requests for code review, release notes for each public version, a changelog for user-visible changes, and tags that connect repository states to releases. Semantic versioning can indicate whether a release contains breaking changes, new features, or bug fixes. A contribution guide can state how users should report problems, what information a useful bug report should contain, and whether outside contributions are welcome.

Transparency also includes limits and maintenance expectations. A project can state whether it is actively maintained, maintained for bug fixes only, experimental, archived, or superseded. It can document known limitations, validation boundaries, deprecation plans, and compatibility guarantees. Such statements protect users and authors by preventing unsupported claims of generality.

8.9. Adopt the Principles Retrospectively When Necessary

The principles are easiest and most effective when they are considered from the very beginning of a project. In practice, however, many useful research tools already exist as scripts before sustainability becomes a priority. This is not a failure and does not make the project unsalvageable. The same principles can be introduced retrospectively, step by step. A practical order is:

1.

put the current project under version control;

2.

write a README that explains purpose, installation, usage, and limitations;

3.

separate one reusable function or module from the analysis script;

4.

add one small reference dataset or synthetic example;

5.

add tests for the most important scientific behavior;

6.

choose a license and make the repository public when appropriate;

7.

create a release, archive it, and add citation metadata;

8.

document changes with a changelog and issue tracker.

This retrospective path is intentionally modest. The goal is not to transform every script into a large package overnight, but to preserve enough context for scientific reuse. What ultimately matters is not whether every principle was present on day one, but whether the mature project makes reproducibility, reuse, documentation, testing, citation, and openness visible in practice.

9. Challenges and Future Directions

The first challenge is deciding when a script is worth turning into a reusable tool. Not every exploratory script needs this treatment. A useful threshold is whether the code will be reused by the same researcher, needed to reproduce a result, shared with collaborators, cited in a paper, used by reviewers, or offered to a community. If so, sustainability practices are no longer optional polish, but they protect the scientific claim.

The second challenge is separating general functionality from project-specific analysis. This separation is difficult because scientific insight often emerges while code is still changing. A pragmatic approach is to keep notebooks or scripts for exploration, but move stable functions into modules once they are used more than once. The analysis can remain flexible while reusable behavior becomes testable.

The third challenge is documentation depth. Too little documentation prevents reuse, whereas too much documentation can become outdated. Documentation should therefore begin with the user path, i.e., what the tool does, how to install it, how to run a minimal example, what assumptions matter, and how to cite it. API documentation and advanced tutorials can grow later.

The fourth challenge is testing during active research. Researchers may feel that tests are premature because the method is still evolving. In practice, tests are most valuable during evolution. They protect known behavior while allowing the implementation to change. Tests can start with small examples, edge cases, and unit conversions rather than full end-to-end validation.

The fifth challenge is maintenance. A project can be useful even if it is not maintained forever, but users should know the status. A repository can state whether it is actively maintained, maintained for bug fixes only, experimental, archived, or superseded. Transparent maintenance expectations are part of responsible open science.

Future work should make sustainable research software easier to adopt in ordinary research settings. This includes better templates for small projects, clearer institutional guidance on licensing and citation, lightweight review criteria for software that accompanies manuscripts, training that treats software as part of research data management, and repository metrics that distinguish archived code from maintained community tools. AI-assisted coding creates an additional need for review practices that document how generated code was tested, corrected, licensed, and maintained. The long-term goal is not to require every researcher to become a professional software engineer, but to make accountable software development a normal part of computational research.

10. Conclusions

Project-specific scripts are essential starting points for computational research. They allow researchers to explore data, test ideas, and answer concrete scientific questions quickly. The problem is not that scripts are small, informal, or written for one study. The problem appears when the context around a script disappears while the code continues to support scientific claims. Sustainable scientific software emerges when that context is preserved. Modular design separates reusable logic from local analysis. Version control records change. Automated testing makes expected behavior explicit. Documentation explains use, assumptions, and limitations. Public availability and open licensing make reuse possible. Persistent citation gives credit and identifies versions. Transparent development shows how the project evolves. These principles work best when they are part of a project from the beginning, but they can be adopted retrospectively. They also become increasingly important as AI-assisted and agentic coding accelerates the creation of software artifacts. Faster code generation increases the need for slower scientific accountability. Over time, repeated use of these principles can make them part of ordinary research practice. Decisions about structure, testing, documentation, licensing, citation, and transparent release become less like additional tasks and more like the default way a computational project is started and maintained. Sustainable research software is therefore not merely a technical preference, but part of how computational research becomes reproducible, reusable, creditable, and trustworthy.