There is currently a trend to produce “just enough” documentation in software development. We should however not forgot that what we might estimate “just enough” today when everything is fresh in our mind could transform itself in “not enough” three months later. Here are some quotes about documentation in software development that I found in the book “Managing the Unmanageable – Rules, Tools, and Insights for Managing Software People and Teams” written by Mickey Mantle and Ron Lichty.
“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.”
Eagleson’s Law
“Documentation is like sex: When it is good, it is very, very good; and when it is bad, it is better than nothing.”
Dick Brandon
I will add another quote found in the same book:
“Does a good farmer neglect a crop he has planted?
Does a good teacher overlook even the most humble student?
Does a good father allow a single child to starve?
Does a good programmer refuse to maintain his code?”
Geoffrey James, The Tao of Programming
How many times have we been in the first situation where things that seemed “obvious” six months before are not anymore today with a fresh look. And I don’t even want to talk about the code we write in the first months when we learn a new language or framework. Often it really helps to add a little bit of documentation about our code objectives or why we use specific algorithms. Sometimes you can think that we don’t need to do it for other people, but we might indeed be the main beneficiaries of documenting our code or design decisions.