Write That Down!
Even when I was a kid in school I hardly wrote things down. That’s why we had textbooks after all! I was baffled by other students in college furiously transcribing every word that came out of the professor’s mouth. Now I have a career in the world of software where we track everything. Git holds all the code commits, email is never really deleted, and project management and issue tracking tools keep track of what we’re doing and have done. How could anything go missing?
I constantly looking for things and cannot find them. I get a bug report, look at the code and say to myself “That is obviously wrong, let’s fix it.” I look at the offending commit that introduced the bug (of course it was me). But what is not there? The reason for the change. So I look at the project management tool we use. And someone definitely asked for a change, but, I’m still not sure why. So I search through my email for the few days before I made the change, and…nothing. I still cannot really figure out why we all decided to make a change which introduced a bug.
Or, worse yet, someone asks for a change. All well and good. Then a month later, someone asks to change it back. So you shake your head and make the change. Then someone is confused why this is happening, and calls a meeting and invites you to help figure it out. What are you going to bring to this meeting? Did you write anything down? I never used to. Now I do.
Now I have a notepad next to my laptop. And I have a notebook on the shelf. I make better use of git messages and write down who asked for changes. When working on a feature, or a bug, and find something…“interesting” I make a Github wiki entry explaining it. I write a comment in the code base explaining it. There are two kinds of documentation — useful documentation, and redundant documentation.
No doubt many people have told you to comment your code. I hope many people have told you never to comment a loop with // loop over the array. That is not increasing clarity, its just duplicating what the code is doing. Adding noise, not signal. My contention is that comments are rarely useful for explaining “What this code does…” but rather, explains “Because of X, we are going to do…”.
Future you is going to be very happy if you start documenting the intent behind what you’re doing. Good code is easy to read. Bad code is capable of being understood with time. But code doesn’t tell you why you’re doing all this work in the first place. Maybe something has changed and you don’t even need this code anymore — deleting code is the most satisfying feeling. But you won’t know unless you know the intent, the purpose, of the code. And the rest of the folks you’re working with are going to be very happy as well.
If you write everything down (and make it public), they won’t need to tap you on the shoulder when you’re in “The Zone” to ask. When someone wants to set a meeting to understand why things are “The Way They Are” you already captured that information. You can send them the link and kill the meeting (Ok, maybe killing meetings is more satisfying than killing code).
We only have so much time in our life, and we already work long hours. Let’s make future us happier by writing things down, so we don’t have to figure it all out again. We figured it out once when we wrote the code. So capture the knowledge in that moment in time. And Write It Down!
