This morning I listened to an interview with Leslie Lamport, a computer scientist who is also known as the initial developer of LaTeX.
One of his statements was that coding should be trivial. The complex stuff should be dealt with before coding, by writing specifications, by creating diagrams and by the use of modeling tools.
This is not the first time I hear such a statement. In fact I keep hearing them again and again. For quite a while I believed that this is the right approach to software development myself.
It just doesn't work, at least not effectively. And there are reasons for that.
When coding, you have excellent tools that provide instant feedback:
An IDE with syntax checking search functionality, autocompletion, refactoring tools and so on.
A compiler and linker or an interpreter that provide more or less descriptive error messages and warnings.
Static analysis tools
These tools help you doing the right things and prevent you from creating bullshit.
When writing specificaltions or other design documents it is completely different. Your word processor doesn't care if what you type make sense. Neither does your favoutite diagramming tool. You have no feedback. As a result there will be errors in the design. These errors will only be found during implementation. (Normally the design documents will not even be updated, but that's another story.)
Now some people argue that the lack of feedback can be resolved by using modeling tools instead of word processors and diagramming programs.
There are modeling tools that seem to work well for specific tasks. Probably for relational database design. Maybe for state machine definition in embedded systems design. But I have not seen any modeling tool for general software development that comes even close to providing the benefits listed above. These things have been promised for at least 30 years and still don't seem to exist.
But what makes people so afraid of code? I don't know, but these possible reasons come to my mind:
This is what I call the write-only code mindset. People see code as the final product of the software industry. In most other industries, final products are extremely expensive to modify. I agree that this can also be the case with code - if the code is a mess - but it shouldn't be that way. That's why we have refactoring and code reviews.
People obsessed with design documents often don't code themselves or haven't coded for a very long time. Their notion of coding is like writing assembly instructions, maybe C or Fortran. They don't know about the level of abstraction and the expressiveness that modern languages offer with features like interfaces, modules, generics or higher order functions.
I don't argue against planning parts of the design before coding. I also understand that design documents are useful to communicate, especially with people who don't code. My point is that it is more efficient to do as much as possible in code and use external documents only if required.
Of course this only works if you take measures that prevent your code from turning into a mess. The most obvious are refactorings, code reviews, standards and of course coders that know what they are doing.
Note: These issues are less severe in agile development because the cycles are smaller but they still exist.