Stupid Question 50: When should I document? And what is the best way to do it?
I know this is another one of the ‘It depends’, but as always I am curious about the on what.
Let’s share first: I don’t document at the moment and I haven’t been documenting. I’ve kept what I consider a nicely structured code, with good naming conventions and hoped that the code would speak for itself. But I know that it does depend on the project. Here is one personal experience I’ve had where documentation would have been nice:
First large project I was involved in had out-commented code ( :( :( :( ) and thank-you-for-stating-the-obvious comments (connectionstring comment: this is the connectionstring). The project also had some excel documents attached that described the economy system (just a part of the large system) and the different codes and how they worked, but no referral to the source code so it was a separate document. Here and there a few comments would clear things up, but it took quite a while to figure out what was happening in the code. It was poorly structured and had bad naming (x and y variables and switching between Swedish and English names, and ‘funny-names’). The project itself was very domain specific and we (two devs) lacked domain training, there was nobody available to explain the code as the owner of the product did not have any contact with the responsible developer(s).
Then and there, some sort of documentation would have been great, as we would have managed to get more things done and even refactor the code somewhat- or at least provided some guidance to the next developer.
I always wondered how do you best serve up a source code, and when do you document, and how do you do that the best?
Last modified on 2012-09-22