If you had to rank the following items (yes, it'd be great to have all three -- get in line), how would you rank them?
Well factored code
Good unit test coverage
Great documentation (comments, requirements, UML, etc.)
Seeing as how this page is living in AgileDevelopment, it's probably no secret where I'm going ... but I'm going to have to rank unit tests first. Gimme passing tests any day over clean code and docs.
DocsCannotBeTrusted ultimately, so it's easy to put them last. But if I have to choose, give me the big ball of rat's nest spaghetti as long as I have tests that pass.
Passing tests are a prerequisite for refactoring, first off. RefactoringIsNotRedesign, it's keeping the functionality exactly the same but improving the internal structure. Without an easy way to verify the functionality hasn't changed during the refactoring, you could be breaking stuff. So, if I've got passing tests, I can start tacking the web of doom that is my codebase.
If I've got really clean code and superb documentation, when additions/changes come I don't have an automated way to help me make sure I'm not breaking existing use cases. DocumentationIsNotExecutable -- if I write my 10th use case, some person is going to have to review the previous 9 to make sure there's no logical conflict in the design. And English is rather ambiguous, which is why we write software in the languages we do instead of English. It's hard enough within a highly constrained vocabulary to get it right.
Michael Feather's article, Before Clarity makes a similar point, showing a great example of clear code that isn't very testable, and his own willingness to reduce the code clarity in favor of testability.
tags: ComputersAndTechnology AgileDevelopment
