A few weeks ago Scott Adams (of Dilbert fame) wrote a blog post about the context of a message. One of his points was that the context that a message is presented in affects how the message is received. Saying the same words at a standup comedy club and at a funeral won't have the same affect. This is related to a thought I've long had about software design documentation. We all have a context in our mind, but that of a reader is probably different.
A specific example of this difference came up at work recently. Asok, Alice, and I (not their real names) were discussing a new feature we wanted added. The feature was something Alice and I needed to support our project, but it required a change in Asok's code. Over the course of an hour long meeting Alice and I kept suggesting changes to Asok's code and he kept telling us that what we were suggesting didn't make any sense.
So why did Asok keep telling us our suggestions made no sense? It wasn't arrogance, he was right. Our suggestions didn't make sense in the context of his code. It was a lack of understanding on Alice and my's part. We were looking at database and classes, and based on their names we were making certain assumption that turned out to be wrong.
Why didn't Alice and I understand Asok's design well enough to make good suggestions? We both have plenty of experience in the field, so it wasn't that. It would be easy to blame poor naming of databases and classes on Asok's part, but now that I understand it, I'm not sure I can come up with anything better. Really it was just a matter of context. Asok had worked on this system for months, and everything fit into a model he had in his head. Alice and I didn't have that model, so we made up our own. As often happens, the model we assumed didn't match reality.
How should [we] document our designsThis, to me, is the big problem of software design documentation. I have been on both sides of this problem. I have seen people completely mangle my code because they didn't see the "correct" ways and places to extend it. I have also mangled others people's code for the same reason. This is how unmaintainable behemoths get created. The challenge is: how should Asok, Alice, or I document our designs such that the context we have in our head is conveyed to the next person?
Some people say that the code is the documentation. While the code is the reality of today, the context of the code shows how to extend, modify, and use that code. Sharing this context from the code writer's mind is crucial to code being able to be maintained beyond the original author.
So, I guess this is another one of those posts where I point out a problem and have no solution. Do you have a solution?
2 comments:
In the "the code is the documentation" I am a big fan of inline documentation tools like Javadoc or Doxygen. They are low impact for the developer, but also generate nice relationship diagrams and easily (and automatically) updated documentation.
This makes it easier for the new or outside developer to get that "bigger picture" of how all the code fits together that is hard to do looking at only a few isolated classes.
I am also a big fan of inline documentation tools. However, for any application of any size, I think code level documentation (including relationship diagrams) is too low of a level to really explain the bigger picture of interactions and responsibilities.
Post a Comment