I don’t document because I know what I’m doing. Seriously. I sit down in front of the computer and beautiful code flows out of my fingertips. No idea how I do it. It’s like digesting for me. It just happens. For me, with my vast experience, my code is so obvious that I can’t think of any question someone might have (okay, let’s just say I need a bit of distance to come up with questions, say a year or so). For me, it’s as simple to understand as hello world. So why make things worse by adding unnecessary comments?
I do understand that other people see this differently but that doesn’t help. I’m not those other people and I simply can’t think what questions they may have. In my case, the solution was unit tests. I need them anyway (they make me more productive) and for the rest of the team, they serve as example how to use the code I write. This is much better than documentation because
1. a test is small, so the answer to your question lies in 10 lines of code. 10 lines of code can’t take long to understand.
2. it is always correct and up to date (unlike documentation which tends to rot)
3. after getting used to test things, you feel how it improves your output (in all ways); documentation, OTOH, is always a drag (“we have to do it … not again … oh man!”).
Tagged: Documentation, Testing
