It’s a basic truth in programming. When you get interrupted before coming to a really good stopping point, you are screwed. Life happens. And reality is cold and harsh.
Sure you intend to comment about what needs fixing and where you left off, but past you always provides less reminding than future you desperately needs. Future you can be really dense.
The very worst moments happen when you break off in the middle of refactoring. That grand design you had in your head, the one where every piece fit together like a stunning mosaic? It’s gone. Duct tape, band aids, and a bit of WD-40 are all you have to look forward to.
Past you and future you are never friends.
If you’ve ever written a comment like “// The methods in this class probably don't work the way you'd expect based on their name
“, you know what I’m talking about.
Never underestimate future you’s stupidity. Comment, comment, comment and while you’re at it, write tests. Tests can save you the whole “What I was doing here?” because you can just look at what is broken and what you expected to work.
It’s better to write less code and make up that time by explaining the code you did write better.
Sure, it helps to leave in a “TODO:” where it counts (“the performance is really bad here”) but while you’re at it, try to leave a few ideas about what exactly is going wrong, and what hypotheses you have rolling around your soon-to-be-extinct neurons. Past you understood things. Future you is clueless.
It always costs less to fix things in the past because you’ve invested in uploading the full design into your brain. Re-upping that design and getting back up to speed involves huge penalties.
Remember these core lessons:
- Future you is thick as a plank.
- Comment as if you are writing for a particularly dimwitted stranger, especially when that stranger is you.
- Build tests. Add examples. Fill in structured document fields. The more you comment now, the less grief you’ll experience in the future.
- Past you is a total jerk.
5 Comments
Past me isn’t a jerk, past me is a naive optimist and thinks far too well of me. Which makes sense, because there he is, writing some cool code, thinking he’s smart, and he thinks I’m going to be _him_, when in actuality, I’m some seemingly unrelated guy who isn’t even smart enough sometimes to remember that I was him.
A great idea is using snippets (I use Alfred) to expand text into a template that you can fill out. For example, :bugtodo: might expand into:
TODO: WhatIsWrong (Why: hypothesisHere)
You can have a bunch of different text expansion templates to better comment your code quickly.
I have a textexpander snippet, “You Are Here”, which just stubs out a decorated five-line comment where I then write a few sentences describing my mental context and frame of mind before I walk away from the keyboard. It makes future-me a much happier client.
This post made me remember a lot from the Pragmatic Programmer book.
Really good insight!
[…] without an intro, this wastes time for the reader, and can lead to bugs when other developers (or future-you) try to change […]