A while ago, for a previous gig, I wrote a module for generating billing reports from a database.
That module’s logic was driven by some specific rules that were not dictated by the business notion of “billing” itself, but rather by the way database developers had done their work.
Simply (!) put, they developed a set of stored procedures that would run other stored procedures owned by another entity (that was externalized probably for financial reasons). Those procedures would extract the data from the external entity’s database and pass it to our procedures which would fill a temporary table whose view we would be able to access to retrieve our data. Phew!
So two years after that someone from that company leaves me a message on my mobile asking if I could call him back regarding that module, because he would like to understand how it behaves.
Well, I’m sorry!
I’m sorry but the billing module itself was not complex: the rules it has to bend to in order to do its work are, though. And these have never been documented, neither by us or by our team of database developers who wrote our stored procedures.
I’m sorry that you were more worried by delivering that reporting module in time, and less worried about documenting what we actually were trying to implement.
I’m sorry that I never got the proper time to document afterwards what was done to implement this. “Communication over Documentation“, I agree, but I think I should have at least documented the core concepts.
I’m sorry that the tests I did for that module are probably incomplete and confused, because I didn’t get the time to make those. Good tests are a great source of documentation, and I guess they certainly would have been helpful now.
I am sorry that, once again, after years in the business trying to convince people on documenting not their code but rather their knowledge, nobody actually paid attention to me.
I am sorry that I am only a human and cannot remember the implementation details of what I coded, two years after. Two years is a long time, and my brain is unfortunately cluttered with happy memories of my wife and children, instead of endless lines of code.
But most of all, I am sorry that I have not taken a stand two years ago to tell you that, no matter what, nothing would prevent me from doing all those things. Because it’s part of my job as a professional developer.
And therefore now I have regrets.
Forgive my sins, Uncle Bob: that’s a failure I’m now trying hard to prevent.
Cheers!