Note: Do not try this at home! XP does in fact recommend doing some documentation, as needed. The C3 team did very little and more or less got away with it. Each team’s need for documentation is different, and needs to be accomodated.
There is some written documentation for the software, more commonly interpreting requirements than documenting design. Sometimes we document an approach to some particularly difficult area. We “never” document code. (We rarely even comment it.)
Here are some good reasons why we do not do more documentation:
- We do not believe that it would help us go faster;
- We do not believe that it would make the system more reliable;
- We do not believe that it would make the system more maintainable.
Here are some good reasons why we should do more documentation:
- It might help other groups benefit from our process;
- It would make interesting reading to our customers;
- It would serve as the basis for useful papers in journals and conferences.
One area that may concern you is our use of CRC cards. We generally do not write anything on the cards, or if we do, we might write the class name. We move them around, touch them, hand them back and forth, let them act out the process we’re designing. Then we throw the cards away and write the code!
You may ask how we later know what the design is, since the cards are gone. Our answer is that the design is represented in the code. If we did have a document, it would either be out of date, or we would have to spend time updating it. We make the code readable, and perhaps use a class comment to describe what a class does. And our high level of communication, and the fact that we do not practice code ownership, ensure that we all know what we need to about the entire system design.
We have written some literate programs for parts of the system, early on in the process. Like most system documentation world-wide, these were not kept up to date. Developers did not enjoy the process, nor find it useful enough to continue.
Should we do more? We don’t know. Will we suffer at some time in the future? We don’t know. We stay alert to signs that we need to change our process, and if we see signs that we need to do more documentation, we will do it.