Code Documents Itself
“The code documents itself!” is nonsense unless everyone thinks exactly alike, and that would be a sad, sad world indeed. So, documentation it is!
Forgive the snotty intro. I’ve been sounding like a broken record when it comes to spreading knowledge in engineering (and other) teams - wherever I’ve worked for the past 10 years or so. Knowledge sharing can take on many forms, pair programming being one of them; and written documentation, another.
Going from the “self-documenting code” illusion to a usable actual documentation is a piece of work. More yet, it needs to be part of every piece of work: documenting what’s being built has to become a standard task in engineering. Just like (hopefully) writing tests. Only when this habit is ingrained, documentation will flow from everyday work like code. Not effortlessly, but habitually.
A description of a structured journey is found in this nice article.
Tags: work