The posting raises quite a few questions about the viability of maintaining design documentation, issues and concerns related to maintaining the synch between code and design artifacts, and the use [or abuse] of diagramming efforts.
Here's a comment I posted:
An interesting discussion you've raised here.I should also clarify that in my particular example cited above that there was zero support to clean-up / prune the dead code from the system - given the intense competitive market pressures, speed of execution required by the business, cost constraints of resource limitations, and other higher business priorities.
When approaching a new large code base, I tend to favor a combination approach of static analysis / model generation tools (deriving the meta view information from code as much as possible) - and adding a lightweight layer of additional (higher-level) architecture and business-process views.
I have encountered numerous engineers (and quite a few architects) who declare that the code is the design - and that it is the end-all, be-all of documentation.
In my experience, those folks are usually not working at the scale of software complexity that my client engagements entail. Their approach doesn't scale well when you need to communicate information to non-engineering team members, and would be very problematic if you need to share design considerations with outside 3rd parties (i.e. concerns related to code-based documentation resulting in excessive scope of disclosure, IP disclosure risks, security exposure risks, etc.). It also makes it exceptionally more difficult to rapidly on-board new engineers and architects.
I can cite one illustrative experience with a past client that illustrates the pitfalls of those who put their trust in the code explicitly as a means of deriving the "true" design/architecture of the system. In a system of ~1M lines of code, that had grown over almost a decade of layering on additional functionality, perhaps 30-40% of the code was no longer used, sat in "dead" areas of the system - and was manifestly misleading about what the system did - and how it did it. Repeatedly, in design review, after design review - team leads would correct my stated assumptions about what the system did in a particular case with the refrain "Oh. That code isn't used anymore". Frustrating doesn't even begin to describe the experience of trying to rely on the code to develop an understanding of THAT system. A set of high-level architecture diagrams - supported with high-level business process flows were exactly what the doctor ordered in that particular situation.