本文探讨了软件设计文档的重要性及其实用性。通过对比传统CMM倡导的全面文档化与敏捷开发中对设计文档的质疑，作者提出了一种实用主义的观点。认为设计文档应该作为业务解决方案与代码实现之间的桥梁，并强调了其在架构描述、接口定义等方面的作用。
How to write design document? Are you kidding? After all we have had many years experience in design document.
These days I have done some design work for Automatic Claim Handling and Letter.
I reviewed previous design documents and kept thinking what should be putted into the document and what should not.
Actually, I am not alone in this issue. In software community, it’s always a hot controversial topic. Extremely there are two distinct voices.
1. CMM advocators insist on tons of documents including comprehensive design document
2. Some Agile advocators speak out design document is useless and design is dead
Eventually, I find myself at the center of this argument. I am not 空头, I am not 多头，I want to be “滑头”, I always want to be pragmatic.
So what’s a design document for?
Basically it acts as a bridge between business solution and code implementation. Dose the document stuff really help it?
Where the answer is yes, I intend to move forward, where the answer is no, action will end.
Let’s have a look at the advantage and disadvantage of design document.
Advantage:
1. It’s good at describe the whole architecture in high level and lead in a right direction
2. It’s vivid and expressive with many diagram, notation and easy to communicate
3. In interface design, it can be a deliverable contract with outer system
Disadvantage:
1. It’s incline to be out of date
First, it's hard to think through all the issues that you need to deal with when you are programming.
Even we can carry it out with extra effort, it’s impossible even for the most experienced designer to foresee requirement change.
2. It’s hard to verify automatically comparing with unit test
Although UML diagram and notation can decrease the ambiguous, it’s still mainly for human-beings. Document is hard to be synchronized with the implementation.
So my principle is to adopt the strength and avoid the weakness.
1. It can never be too detailed for interface contract design document
2. Design document should clarify the boundary with outer system
3. Design document should express high level concern and main point of business solution
4. Design document should setup common convention and pattern.
5. Design document should not run into implementation detail.
6. Unit test should be involved to help to reflect requirement and design.
Remember, it is better to have few useful design documents that you use and keep up to date than to have many forgotten, obsolete documents.
These days I have done some design work for Automatic Claim Handling and Letter.
I reviewed previous design documents and kept thinking what should be putted into the document and what should not.
Actually, I am not alone in this issue. In software community, it’s always a hot controversial topic. Extremely there are two distinct voices.
1. CMM advocators insist on tons of documents including comprehensive design document
2. Some Agile advocators speak out design document is useless and design is dead
Eventually, I find myself at the center of this argument. I am not 空头, I am not 多头，I want to be “滑头”, I always want to be pragmatic.
So what’s a design document for?
Basically it acts as a bridge between business solution and code implementation. Dose the document stuff really help it?
Where the answer is yes, I intend to move forward, where the answer is no, action will end.
Let’s have a look at the advantage and disadvantage of design document.
Advantage:
1. It’s good at describe the whole architecture in high level and lead in a right direction
2. It’s vivid and expressive with many diagram, notation and easy to communicate
3. In interface design, it can be a deliverable contract with outer system
Disadvantage:
1. It’s incline to be out of date
First, it's hard to think through all the issues that you need to deal with when you are programming.
Even we can carry it out with extra effort, it’s impossible even for the most experienced designer to foresee requirement change.
2. It’s hard to verify automatically comparing with unit test
Although UML diagram and notation can decrease the ambiguous, it’s still mainly for human-beings. Document is hard to be synchronized with the implementation.
So my principle is to adopt the strength and avoid the weakness.
1. It can never be too detailed for interface contract design document
2. Design document should clarify the boundary with outer system
3. Design document should express high level concern and main point of business solution
4. Design document should setup common convention and pattern.
5. Design document should not run into implementation detail.
6. Unit test should be involved to help to reflect requirement and design.
Remember, it is better to have few useful design documents that you use and keep up to date than to have many forgotten, obsolete documents.
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
