For many IT people, including myself a few years ago, the ideal software development process would involve the creation of detailed design documents with lots of UML diagrams before a line of code gets written. (This looks like a description of the waterfall model but it's the same with agile, except that the iterations are smaller.)
During the past two or three years, I have completely changed my mind. I still think that a detailed requirements specification with associated test cases is absolutely essential. For large projects, I would also require an outline of the overall architecture before starting to code. But all the rest should be done in code as much as possible. In the ideal case there should be no description of software design except the code itself.
How did I come to this conclusion? Here are some arguments:
Tools for writing documents or creating diagrams provide little feedback. Yes, there are modeling tools that do some consistency checks on UML diagrams but they are limited and come with a lot of overhead.
Without feedback it is hard to recognize and fix errors.
As soon as you write code, you get lots of feedback, for example:
- Errors and warnings from the compiler
- Static code analysis results
- Unit tests
Errors can be quickly recognized and fixed.
To make sure that the code is consistent with your documents you have to check again and again. If there are frequent changes, it is hard to keep code and documents in sync.
There are powerful tools and techniques for refactoring code while refactoring textual descriptions or diagrams is usually hard and error prone.
There is one precondition to make this work: The code has to be easy enough to read and understand. This probably cannot be achieved with Assembler, Basic or Fortran but modern languages (and libraries) are much more expressive.
So if my arguments are valid, there should be a trend towards less or more lightweight software design specification and documentation. Is there any empirical evidence for this trend?