I have been thinking a lot about the merits of documentation in software projects and for good reason too since the time for my project to switch into development mode is neigh…Documentation in the case of this argument consists of class diagrams, abstract interface documentation for other developers to enable client module developers etc - all internal documentation not user documentation which you will have to publish in some form and which may be separate work products.The first question that I ask myself about documentation of software artefacts is - Why bother with it? - If we accept that the fundamental nature of software is changeability - Why have two different artefacts: the code and the documentation that you have to constantly keep in sync when you make a change. The argument made by documentation zealots is that true software engineers will understand the nature of the change and tweak the exsting documents (class diagrams etc.) and then make appropriate changes to the code. I tend to disagree entirely - having been a part of some software product development teams I have seen the documenting for documentation’s sake motto and also the documenting to satisfy the KPA in the CMM motto both of which not only slow the process of software construction but also add a source of confusion for new developers who might read the documents to move forward. I am in no way making an assertion for not documenting your code adequately - all I am saying is we should think of better ways to document it internally i.e. within the code base itself. Any refactoring that is made to the code should also adequately reflect on the documentation - though this might seem similar to documenting it externally- it really is not, since, keeping everything (code and related documentation) in the same place is a better way to maintain compatibility.In my quest for enlightenment I turned to “Object Oriented Software Construction by Bertrand Meyer, where quite succinctly he establishes The Self Documentation Principle as one of the 5 Principles of software construction which he defines as: The designer of a module should strive to make all information about the module part of the module itself this principle when coupled with one of the 5 Criteria for software construction - Understandability - which Meyer states as the ability of a module to be understandable to a reader without the reader having to read all its elements seperately is what should provide the necessary level of documentation for software artefacts.

David West, of “Object Thinking” fame (also a famous SmallTalk programmer) favours the CRC Card Approach - this approach was invented by Kent Beck and Ward Cunningham (thank you God for Agile developers) and it is an informal approach to analysis and design of the various classes you might need in your software system. I seem to like this approach to start with - since it is collaborative, requires a domain expert to clarify how parts of the system under discussion should react etc. From then on I firmly believe that one must have adequate code reviews to ensure that the artefacts have been adequately documented internally to ensure that the Self Documentation Principle and Understandability criteria are fulfilled.