I really loved this post, and experimented what Michel says with my hands in the context of Redis. The Redis code base is in general not rocket science, is pretty understandable and does not use too complex ideas. I simply don’t trust my ability to write complex and correct code at the same time, and so far this approach worked well, Redis is quite stable all considered. However the file implementing replication, replication.c, gained complexity very fast compared to the other parts of Redis over the years. It’s 2500 lines of code, while for example cluster.c is 5000 lines of code, but even at 2x the size, cluster.c is simpler to understand. The reason is exactly what Michel says: a code that matches a mental model. How replication.c got its complexity is easily explained. Redis replication was extremely simple at start. Just streaming replication between master and slave(s). You connect, get the initial payload representing the dataset on the master, and starting from there is just streaming of write commands received by the master (from the clients) to the connected slaves. Then we added partial resynchronization. Later we added in-memory replication (called diskless replication) for environments with slow disks, chained replication, and so forth. Instead of redesigning the code in order to cope with the new complexity, I usually approach the issue in a different way: I modify what I’ve with the minimal set of changes to make it working. This usually is a good strategy in my opinion, since to make something <i>truly</i> general sometimes makes it more complex than having something simpler with a few exceptions to handle corner cases. However this approach does not scale a lot, eventually the code is structured like if the problem was simpler, but has a lot of exceptions. When you reached this point, you can no longer build a mental model of how the code works. The result was that we (Redis Labs Redis core team and I) recently found a number of bugs in corner cases that could arise mixing diskless replication with PSYNC with other unexpected events. While fixing those bugs I started to refactor replication.c in order to make it structured in a way that it is possible to create a mental model about it again, so that the actual layout of the code reflects a bit more what are the moving pieces: the action of creating the initial synchronization payload, the slave attempting a partial synchronization, and so forth. There is still work to make, but in general, its very important to write code for which a simple mental mode exists <i>and matches</i> the code layout.