A realization about code complexity and clarity
In the process of writing yesterday's entry I had one of those obvious in retrospect insights:
We all know (or at least have been told repeatedly) that just because something about the code (such as where a name comes from) is clear to you when you write the code, that doesn't mean it will remain obvious later (or be obvious to other people). One of the core reasons for this is context, specially how much context is in your mind.
When you are writing the code, you generally have the maximum amount of context possible in your mind; you just wrote the code, or at least you are working on it intensively. You will lose at least part of this context over time, possibly a lot of it, and of course other people don't have it to start with or at least don't have very much of it. To use yesterday's issue as an example, when you are writing the code of course you know off the top of your head where a certain function comes from, because you just wrote it. If you're using a rule for what functions are defined where, of course you also remember that rule and how it applies to this particular function. But all of this context is going to fade from your mind over time if you're not actively working on the code.
This means that you need to overshoot on clarity, because your view of clarity is being influenced by the context you have. Just being clear isn't enough; things need to be obvious, maybe glaringly obvious to the you that has maximum context, because that means they have a chance of still being clear to someone who has a lot less context.
(It is my personal opinion that clarity and obviousness are better than trying to write enough introductory comments to recreate some approximation of the context.)
PS: if you are writing code that is intrinsically complex enough to require significant context to work on, it might be worthwhile to explicitly note this at the top of the code, more or less as a warning sign. I wouldn't necessarily try to recreate the context, just have a comment that says 'all of the code and comments here assume deep familiarity with ...' or something similar.
One reason I like having this insight is that it creates a grounding for a lot of things I've had hammered into me about creating overly complex and clever code.