On this Saturday afternoon, I thought I'd write up what I consider a healthy open source environment and what is good open source code. Most of it is common knowledge, but I thought I'd write down a list. (1/23)
Almost all of the discussions, whether it is about bugs or about the project's roadmap, should be done publicly in issues. This allows everybody to be part of conversations, even when they were not initially part of it. (2/23)
The one major thing that can be decided only through instant messaging is the order in which to tackle issues. In other words which changes are more urgent than others. Whether to make a change should be decided in issues/PRs. (3/23)
You can of course design things and decide which changes to make offline/privately, but it's important that the reason for making a change be explained online publicly and that a bit of time be given for outsiders to discuss it. (4/23)
There shouldn't be any mandatory or periodic synchronous meeting. Synchronous meetings (including calls) should include only people that want to be in the meeting. (5/23)
Encourage people to open issues if they think something is not working as intended or if they want an improvement. There shouldn't be any precondition to opening an issue, other than the issue being descriptive/comprehensible. (6/23)
As a consequence of the previous point, there should be people whose full responsibility is to triage and answer issues and PRs. They make sure that everything is cross-referenced, close duplicates, ping the right people, and so on. (7/23)
If a change is made against a piece of code that a person has interests in, then that person should be at least aware of it and not be opposed to it. Nobody should have to maintain code they don't agree with. (8/23)
The previous point should also be enforced by the people who triage issues/PRs. Programmers shouldn't have to also read every single issues/PRs to make sure they're not accidentally missing an important discussion. (9/23)
Use rustfmt. The point of rustfmt is not to make the code nice, but to avoid losing time discussing the code style or applying code style fixes. (10/23)
Any rule about the code should be enforced by CI if it's reasonable to do so. For example, if a certain dependency is banned, then as part of CI should be a script that makes sure that this is the case. (11/23)
Similarly, rules such as for example labels that should be applied on issues/PRs should be enforced by bots. Doing this manually is cumbersome and prone to mistakes. (12/23)
Deployments should also be as automated as possible. The number of steps required to deploy something, and the possibility for the mistakes, should both be as little as possible. (13/23)
I like TODOs in code. I put a TODO every time there's for example an opportunity for optimization that I don't have time to make. TODOs should however be clear about what they are about, not just "TODO: fix this" with no context. (14/23)
(continuing on last point) Assuming that everybody does the same and applies TODOs on parts of the code that they think should change, this makes it possible to judge a code's maturity by the number of TODOs. (15/23)
Code should be as isolated as possible. The objective is that the amount of knowledge required to understand a piece of code and/or determine whether it is behaving correctly should be as little as possible. (16/23)
Ideally, it should be possible to read the source code of a module alone and fully understand it, without having to jump to a different module in the process. (17/23)
Documentation shouldn't be outdated. I'm a fan of Rust's intra-doc links and put them everywhere, as they allow me to detect when a change to the code breaks the documentation. Putting a lot of examples also achieves the same goal. (18/23)
Don't use concurrency when it's not needed. Benchmark first. Concurrency. Is. Hard. Anything concurrent should be isolated and be extremely precisely documented. The rest should be state machines. (19/23)
The most important part of the code is its API. It's what allows to determine whether its implementation is correct. It's usually very useful to start by the implementation, but that doesn't invalidate the point. (20/23)
However don't go to the opposite extreme and totally separate interface and implementation. That's also not possible. Details in the API (e.g. whether to take by reference or by value) usually depend on the implementation. (21/23)
Mistakes will be made. Refactorings will be necessary. That's inevitable. It's when that happens that you'll be glad you have tests and a precise API to conform to. Projects fail when they don't do necessary refactorings. (22/23)
I think I summed up everything. Thanks for reading, and have a nice weekend. (23/23)
