Eagleson's law

Eagleson's law says: any code of your own that you haven't looked at for six or more months might as well have been written by someone else. It circulates in collections of programming laws; who Eagleson was is unclear. The idea is familiar to anyone who has run git blame on a confusing line and found their own name.

#How it works

While you're writing code, your head holds most of the context: the bug you were avoiding, the option you tried and dropped, why the odd special case exists. None of that is in the code. After a few months the context is gone, and you're left with only what you wrote down: names, structure, comments, tests and commit messages. If those don't explain it, you have to reverse-engineer your own reasoning.

It follows that the reader you should write for is not a colleague who already knows the system. It's a capable stranger, and in six months that includes you.

#What to do about it

• Write the why, not the what. Comments and commit messages should record intent and rejected alternatives; the code already shows what it does.
• Use history. git log -p and git blame lead from a line to the change and message that introduced it, so the message is worth writing well. Exploring history covers git log, and git bisect finds the commit that changed a behavior.
• Let tests document behavior. A test named for the case it protects explains a special case better than a comment, and fails when the explanation stops being true.
• Prefer boring code. A clever trick saves a minute now and costs an hour every time someone, including you, reads it later.