One specific challenge, when writing code as a scientist, is that we care a lot about getting the right answer; but of course, the right answer is not always obvious. So we should be very careful with the code we write. A piece of code that crashes is annoying; but a piece of code that runs, and give you the wrong answer can compromise your science and your career. This guide will help you adopt practices that make it less likely to introduce mistakes in your code, and more likely to catch them. Hopefully, this will let all of us write code we can trust more.
Good principles in scientific computing can help you write code that is easier to maintain, easier to reproduce, and easier to debug. But it can be difficult to find an introduction to get you started. The goal of this project is to provide reproducible documents you can use to get started on the most important points. You can use these lessons on your own, or as a group.
This material is aimed at people who have already interacted with a computer using a programming language, but want to adopt best practices that make their code more robust. It can also be used to facilitate the onboarding of new people in your lab or in your project.
Scientific computing should not be adressed only to those of us with terabytes upon terabytes of data, or the need to distribute computations across thousands of cores, or need GP-GPU programming. Most of us researchers do not have these needs, and we will not discuss them at all here. But if you do these sort of things, you are more than welcome to contribute your valuable experience to these lessons.
And do you want good news? You don't need to install anything! We rely on the Binder project, a cloud-based service to run reproducible documents. We will use the Julia language; but you don't need to know anything about it either. We will keep the discussion very general, and not use any of the (very cool!) language-specific features and syntax.
In fact, you will see that good practices for scientific computing have very little to do with tools and technical things; instead, they rely on thinking about programming in a slightly different way. You will be able to apply these principles to any language you prefer to use.
📓 Lesson 1 - using notebooks
- 🏁 Start the lesson!
- 🚩 Report issues or give feedback
- Contents:
- cells and states
- order of execution
- exporting and saving your work
- 🕐 approx. 10 minutes
🔃 Lesson 2 - the flow of execution
- 🏁 Start the lesson!
- 🚩 Report issues or give feedback
- Contents:
- programming as a language (with only three words!)
- if, for, while - what do they do?
- moving across loops
- 🕐 approx. 25 minutes
- ℹ️ early draft
- Contents:
- advantages of modular code
- writing functions (and commenting them)
- arguments
- type stability
- Contents:
- defensive programming
- using types as input control
- testing
- Contents:
- using print
- debugging strategies
- messages, warnings, and errors
There are a number of ways to contribute. Before you start, please have a look at our Code of Conduct. It boils down to be nice and respectful -- no contribution, no matter how amazing it may be, justifies or excuses bad behaviour.
The first thing you can do is comment on Issues that have the "Request for feedback" label. They represent situations for which we are actively seeking community feedback, and anyone is always welcome to chime in.
If you are not sure about opening an issue, you can use the chatroom. We'll be glad to have a more informal conversation with you!
If there is a more specific point you would like to raise, you can create a new Issue, and explain your idea, critique, or comment. And of course, you can always browse the current Issues, to get a sense of what is being discussed.
If you want to contribute more, then great! Have a look at the contribution guidelines first, to get you started with setting up a development environment. You can have a look at "Good first issues", if you want some inspiration.
Comments, ideas, feedback: Hao Ye, Philipp Bayer, Tim Head, Ethan White
In a rush? Yes you are. We suggest "Good enough practices in scientific computing" to get you started.
A little bit more time? We think "Best practices in scientific computing" might suit you.
Want a more complete thing to read? "The pragmatic programmer" is a masterpiece. I have also heard great things about "Clean code".
If you still have some time, you can read something about ways to improve user confidence in your software, or ways to elevate code as a research output.
