You cannot hold the details of a large system in your head, even if you wrote every line of code.

You’re right, of course, about large systems. There are two ways to deal with those. The first is indeed decomposing into a set of loosely-coupled components. I’m a big advocate of Service Oriented Architectures for this reason. The other is to use abstraction to hide the details, so you only need to hold the high level system design in your head, plus the details of the parts you are working on.

I disagree about notes, however. The problem is keeping them in sync with the code. Every form of documentation suffers from this — you update the code and forget to update the corresponding documentation. This is actual worse than no documentation because your notes are now actively misleading and can cause very subtle and hard to find bugs. Ideally, your code is readable enough to be the documentation, so you never have this problem. This is hard to achieve, though.

Like what you read? Give Dan Quine a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.