James Taylor's Decision Management

Shayne Nelson started an interesting discussion this week with a post titled "Making Software Maintainable - Part I. Shayne talks about the promise of case tools in this context, something with which I also have experience having supported and used various case tools over the years. He has a great comment:

What an industry.... creating products for which the documentation (done at great expense) is generally useless, and sometimes worse than useless, actually misleading or inaccurate. It's no wonder that 85% of all programming effort goes into maintenance. When maintaining code, you're generally working blind

And this is true - you are usually working blind but not just because the documentation is out of date. The code itself is unhelpful. To quote Ira Fuchs

"Programming languages today remain syntactic, abbreviated, and procedural, as opposed to semantic, verbose, and declarative"

And this, I think, is the real problem. No matter how up to date or good the documentation, the code itself must be understandable and editable if maintenance is to become easier. Shayne suggested that a tool like Gamma where a programmer edited the documentation instead of the code is a solution. Having watched these kinds of tools in use I am not so sure. When things must be done in a hurry, or even when less disciplined programmers make changes, there is a perceived need to edit the actual code executing. This becomes the path of least resistance - a programmer knows that a change to the code will "fix" the problem where any kind of indirection is a risk. Add to this the tendency of programmers to always use the most complex features available in a language and it is clear that the problem is programming languages not documentation.

The right question, then, is not "How much documentation is enough?" but "How does this language force me to write code that is easy to read, easy and safe to modify and understandable to business users so that they can help?". I have blogged before about the problem with programmers and some habits of effective programmers but the bottom line is this: Using business rules, and a business rules management system, moves your "code" up a level and makes it more accessible, easier to read and understand, and more stable in the face of change. Fix that first and then see how much documentation you need.