CIO — There's never been a good excuse for not commenting code or documenting systems, even though these practices are every bit as helpful to cost and quality as test-driven development. But let's face it, documenting systems isn't exactly macho and besides, it doesn't give you the ugly job- security of unmaintainable code (take a look at this page for some terrific worst-practice suggestions).

Working in the clouds, unfortunately, can give developers a new excuse: "I don't have any access or control over that (public-cloud) service, so I can't document anything about it."

Uh-huh. So, call their bluff this way: all consumers of a (public or private) cloud service need to document what the service does, how it's used, and what behaviors (including bugs and error conditions) that the consuming side uses or depends on. Immediately, the whine will come: "but that means we have to document the same cloud service in every module we use it." To which your response should be, 'Put your documentation info in a Wiki, a Google (GOOG) doc, or other collaborative system that the entire development and integration team can access."

This pushes everyone toward the best practice for the external interfaces and dependencies of modules and services: a centralized repository whose content is created and maintained by every member of the development team — as distributed as they may be. In my experience, the alternative of having a centralized team responsible for creating and maintaining data dictionaries, entity-relationship models, business-process descriptions, or interface documentation produces only two things: an excuse for not doing documentation or, at best, obsolete or often incorrect tomes.

But is a Wiki the best place to document the internals of a module or the administrivia of a variable? It's not a bad idea, but most of the time developers just won't be in the documentation area while they're hacking code or tweaking a variable inside an app. When they're working in their code, in-line commenting must not just be encouraged: it must be measured. For the code we develop, we don't allow any module to be checked in to the system unless at least 10% of the lines are explicit comments, and another 10% of the lines have in-line remarks. The inline code requirement goes double for test modules, as it can be difficult to guess what a particular routing is testing for, and where to look in the module under test when there is a failure. Your code integration system may already have counters and enforcement mechanisms for this, but if they don't you can typically script it to do so.

Continue Reading