Skip to content

Training overview

As a scientist, your core business is science, not software engineering. Nevertheless, having a good understanding of how best practices in software engineering can help you work more efficiently, make your work easier to reuse, and give your work more exposure is useful.

This training is flexible. It can be tailored to C, C++, Fortran, Rust, Julia, Python, R, or a language-agnostic mix, and the depth can be adapted to the audience.

Core question and narrative

This training is organized around one central question:

How do we turn scientific code into a trustworthy, understandable, and reproducible computational experiment?

The core route follows a single narrative:

Readable code → traceable changes → meaningful tests → documented interfaces → interpretable data → automated checks → reproducible results

Each topic contributes to this progression. Code style helps communicate scientific intent; version control records how the code evolves; testing provides evidence about software behavior and scientific correctness; documentation and data formats preserve meaning; automated checks apply agreed practices consistently; and reproducibility connects the code, data, environment, parameters, and workflow to the reported result. Static analysis supports this route by detecting some implementation defects early; it complements rather than changes the progression.

The agentic AI chapter treats AI-assisted development as a cross-cutting concern rather than another stage in the narrative. It is supporting material, not an additional scheduled block.

The running temperature-analysis example revisits this narrative through one small computational experiment. It is distributed across the scheduled topics rather than taught as an additional block.

The introduction and motivation and conclusions serve as bookends: the opening formulates the question and the closing returns to it through concrete next steps.

An optional hands-on exercise is available to reinforce the narrative after the session. It is self-paced and is not included in the four-hour training time because participants' programming and testing experience can vary considerably.

Learning outcomes

When you complete this training you will be able to

  • explain why software engineering practices matter for scientific computing;
  • explain how version control supports traceability, recovery, collaboration, and scientific provenance;
  • distinguish formatters, compiler diagnostics, linters, static type checkers, broader static analysers, and tests, and explain how they provide complementary evidence about software quality and correctness;
  • recognize the role of code style, documentation, testing, and reproducibility in scientific software;
  • identify scientifically meaningful properties and numerical comparisons for testing scientific software;
  • distinguish between unit tests, functional tests, and code coverage, and explain why coverage alone does not establish scientific correctness;
  • explain how format choice, metadata, validation, and access patterns affect the reproducibility and usability of scientific data;
  • recognize how deployment and continuous-integration practices support reliable scientific software;
  • choose relevant tools for the programming language and project context you work in.

Schedule

Total duration: 4 hours.

Because the training is flexible, the exact schedule can be adapted to the programming language and level of detail requested.

Subject Duration
introduction and motivation 10 min.
code style and conventions 20 min.
static analysis 15 min.
motivation for version control and collaboration 20 min.
testing, including scientific correctness 70 min.
documentation 25 min.
scientific I/O and data formats 20 min.
deployment and continuous integration 20 min.
reproducibility 30 min.
conclusions and discussion 10 min.

The optional running-example exercise is deliberately excluded from this schedule. Participants can complete all or part of it in their own time after the session, using the supplied starter files, checks, hints, and reference implementation.

The testing block may include a brief demonstration of the runnable numerical-integration tests. Completing its test-writing exercise is also optional follow-up work; it does not add another block to the four-hour schedule.

Training materials

The training material is available as this website:

https://gjbex.github.io/Best-practices-for-scientific-computing/

The source repository is available on GitHub:

https://github.com/gjbex/Best-practices-for-scientific-computing

See further training for topic-specific courses that develop these introductory themes in more depth.

Target audience

This training is for researchers, PhD students, research software engineers, and technical staff who write or maintain software in a scientific-computing context.

It is especially useful if your scripts, notebooks, or applications are becoming important enough that they need to be shared, reviewed, tested, reproduced, or maintained over time.

Prerequisites

You should be fluent in at least one programming language. The training is not an introduction to programming.

If you plan to apply the material in a Linux or HPC environment, you should be familiar with those environments as well.

Quick self-assessment

If you can do most of the tasks below in a programming language you use for scientific work, you are likely ready for this training.

  • read and modify an existing script, notebook, or small program;
  • split repeated code into a function or helper module;
  • use the command line to run code or inspect files;
  • explain what input data, output files, and parameters a small analysis uses;
  • recognize when code would be difficult for a colleague to understand or reuse;
  • make a small change and check whether the result still looks correct;
  • use or be willing to learn version control for collaborative work.

If several of these items still feel difficult, the training will probably move too fast. In that case, it is better to first refresh the basics of your main programming language and command-line workflow.

Software and access requirements

To follow hands-on, you need a computer with the tools used for the selected language track. At minimum, you should have access to:

  • a shell environment;
  • Git;
  • a text editor or IDE;
  • the compiler, interpreter, or notebook environment for the programming language used in the session.

For sessions on an HPC system, make sure you can log in, edit files, submit jobs if needed, and load the relevant software environment.

Level of the Material

For participants who already have programming experience, the material in this training is approximately

  • Introductory: 30 %
  • Intermediate: 50 %
  • Advanced: 20 %

These percentages describe the level of the software-engineering and scientific-computing topics covered in the training, not the participants' general programming background.

Trainer(s)