In our model (which is fairly specific to business process applications) the design artefacts include:
a domain data model, with comments on each entity and attribute
a properties file listing all the modify and create triggers on each entity, calculated attributes, validators and other business logic
a set of screen definitions (view model)
However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.
But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.
This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.
Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology, team structure, timescale, tools, etc.).
For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:
A detailed functional design document (aka specification). Generally something along the lines of Joel s' WhatsTimeIsIt example specification, although probably with some UML use case diagrams.
A software technical design document. It is not necessarily detailed for 100% system coverage, but detailed in all the key areas and containing all the design decisions. Being a bit of an UML freak, it'd be nice to see lots of pictures along the lines of package diagrams, component diagrams, key feature class diagrams, and probably some sequence diagrams thrown in for good measure.
An infrastructure design document. Probably with UML deployment diagram for the conceptual design and perhaps a network diagram for something more physical.
When I say document, any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.
As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clearly indicate what the application does, how it does it, and where it does it then you know the support teams are going to give the app the same care and attention they would a rabid dog.
I should mention I'm not vindicating the practice of handing software over from a development team to a support team once it's finished, which raises all manner of interesting issues; I'm just saying it should be possible if the management so desired.
Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.
I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!
发布评论
评论（6）
在我们的模型（相当特定于业务流程应用程序）中，设计工件包括：
但是，这些真的算作设计制品吗？ 我们的框架是这样的，这些定义用于生成系统的实际代码，因此它们可能超出了设计范围。
但事实上，它们承担双重职责是很强大的，因为根据定义，它们是最新的，并且始终与代码同步。
In our model (which is fairly specific to business process applications) the design artefacts include:
However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.
But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.
这本身不是一个设计文档，但我们的单元测试具有“描述”他们测试的代码如何运行的双重目的。 这样做的好处是它们永远不会过时，因为我们的单元测试必须通过才能使我们的构建成功。
This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.
我认为没有任何东西可以取代良好的老式设计规范，原因如下：
我喜欢在设计规范中看到各种信息： 对
单元测试虽然是应用程序开发中包含的一个奇妙且可以说是关键的项目，但并没有涵盖所有这些主题。
I don't think anything can take the place of a good old-fashioned design specification for the following reasons:
I like to see various bits of info in a design specification:
Unit tests, while a fantastic and arguably critical item to include in your application development, don't cover all of these topics.
过去曾参与过许多瀑布项目以及许多临时和敏捷项目最近，我喜欢创建许多设计工件，尽管我无法充分说明它实际上取决于项目的细节（方法、团队结构、时间尺度、工具等）。
对于通用的、基于服务器的“企业应用程序”，我希望最低限度是这样的：
当我说文档时，上述任何内容都可能被分解为多个文档，或者可能存储在 wiki/其他一些工具上。
至于它们的用处，我的理念始终是开发团队应该始终能够将应用程序移交给支持团队，而不必交出他们的电话号码。 如果设计工件没有清楚地表明应用程序做什么、如何做以及在哪里做，那么您就知道支持团队会给应用程序提供与疯狗一样的照顾和关注。
我应该提到的是，我并不是在证明软件完成后将软件从开发团队移交给支持团队的做法是正确的，这会引发各种有趣的问题； 我只是说如果管理层愿意的话应该是可能的。
Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology, team structure, timescale, tools, etc.).
For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:
When I say document, any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.
As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clearly indicate what the application does, how it does it, and where it does it then you know the support teams are going to give the app the same care and attention they would a rabid dog.
I should mention I'm not vindicating the practice of handing software over from a development team to a support team once it's finished, which raises all manner of interesting issues; I'm just saying it should be possible if the management so desired.
设计在开发期间和之后发生了很大的变化，以至于我精心制作的大部分文档都在源代码管理中腐烂了，一旦代码投入生产，它们几乎变成了障碍而不是帮助。 我认为设计文档对于良好的沟通和在开发某些东西时澄清你的想法是必要的，但之后需要付出巨大的努力才能正确维护它们。
我确实拍摄白板照片并将 JPEG 保存到源代码管理中。 这些是我最好的一些设计文档！
Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.
I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!
工作代码...和白板图。
：P
Working code...and whiteboard drawings.
:P