如何写一个软件工程的开发文档？我门不是程序远只是代码狂而已！如何正规？！！！

valhallen 2002-02-26 10:54:02

要抛弃作坊就要正规
一切的一切
软件工程的正式流程是什么啊？
开发文档怎么写？因为文档占总工程的30%-40%的时间，可以写到高中生都可以写代码的程度
代码的规范性怎么规定？包括变量名的定义
印度人的代码就比我们的强很多因为他们规范 2个人写的同程序有很多相似之处
我们的代码都是一个人一个样互不兼容我们都是代码狂放在pc前的时间占软件开发时间的90%以上
如何正规？

...全文

553 37 打赏收藏转发到动态举报

写回复

用AI写文章

37 条回复

切换为时间正序

请发表友善的回复…

发表回复

TechnoFantasy 2002-02-28

打赏
举报

具体的文档是不可能公开的，一般只能公布一些模板和初步流程。

niya3 2002-02-28

打赏
举报

我正在干，也请给我一份，

web369@qiye369.com
或
niya3@sohu.com

yun95791 2002-02-28

打赏
举报

请问那位大哥有具体项目的示例文档？
能给小弟发一份嘛？
wzli2002@163.com

valhallen 2002-02-27

打赏
举报

http://www.powerba.com/develop/project/sample/article/20010601001.htm

DreamMasterZ 2002-02-27

打赏
举报

汲取经验：中国民族软件业的规模化发展之路

　　赴日IT劳工无疑是非常辛苦的，这条打工道路十分艰辛。然而，当他们对着Arshioul吐露心声的时候，他们都无一例外地提高了日本IT企业严格的管理，尤其是软件业规模化发展的流程管理。

　　很多中国IT劳工原来以为到日本去，是去做程序员，到了那里才知道，他是要做“Coding”。要成为一个真正合格的程序员，或者说，成为一名真正能够完成一些代码工作的程序员，日本的软件业认为，他第一步应该从一些极其细小、琐碎的环节开始做起。

　　日本IT企业的工作作风非常细致、非常认真、非常敬业。一些知名IT公司规定代码的变量命名、代码内注释格式、甚至程序中每行的代码数量、嵌套中行缩进的长度和函数间的空行数字都有明确规定。

　　有时候这种规定近乎死板，不近人情，但是所有人都肯定，良好的编写习惯，不但有助于代码的移植和纠错，也有助于软件编写的模块化组合和复用，有利于不同技术人员之间的协作。

　　“国内的某些程序员自以为了不起，叫嚣高水平程序员写的代码水平低的人看不懂。其实，这样程序写出来，时间长了，他们自己也看不懂。叫嚣只能证明他们自己压根不配做程序。”国内某重点大学自动化系毕业的小J回国后来这么说，“代码具有良好的可读性和可注释性，是程序员基本的素质需求。”

　　日本的软件开发与国际通行的CMM软件成熟度模型并不完全相似，但是双方在某些关键流程上惊人得一致，比如书写技术文档。日本IT软件开发要花上30%～40%撰写企划书、介绍书之类的东西，这种文档简直像傻瓜版的操作手册，上面详细写明程序员应该用什么语句，在那些程序段中查找什么字节。

　　换而言之，良好的文档书写习惯使得软件开发把程序员当流水线来使用，实现了高效管理与严格的时间控制。尤其是时间控制，日本的IT企业都有严格的记录，因为这是企业产品盈利与否的分界线。一般在日本，一个软件产品提前完成可以赚大钱，按时完成可以赚小钱，超时完成就只能赔钱了。

　　软件越是高级，功能越是复杂，企划书的介绍也越是详尽。作为日本企业内部高级程序员和系统分析员，研读企划书的时间比例不小。“缺了文档，一个软件系统就缺乏生命力，在未来的查错，升级以及模块的复用时就都会遇到极大的麻烦。”另一个有过IT劳工经验的P说，“我回到国内后，看到同行每天完成工作后都不写技术文档，吃惊得不得了。”

　　最让中国IT劳工惊讶的是日本IT企业的团队精神和协作能力。“这是一种人的基本素质，我个人认为，这也是程序员应该具备的最基本的，也是最重要的职业操守。”有的人领悟般地这么说。“任何个人的力量都是有限的，把高水平程序员说成独行侠的都是痴人说梦。”

　　看来，中国IT人员艰难的海外打工之路带来的不仅有眼泪和辛酸，也有经验和体会。他们中的不少人将在残酷的环境中摸爬滚打，等到他们回国以后，就将成为中国民族软件事业发展的中流砥柱.

转贴csdn it包身工

valhallen 2002-02-27

打赏
举报

对此文的评论：
Jacob_Zhong：自学要走很大的弯路啊，为什么不能在学校里普及规范的编程方法？ (2002.02.27)

txf168：中国软件企业缺泛规范和统一,软件的设计是满足根本的客户需求,追求的短期利益.说白了企业主没有远见.企业很少要刚毕业的和没有工作经验的,企业主一般就是你帮我创造了多少价值,我给你一个零头. (2002.02.27)

echoeyes：的确是体制的问题，软件是个系统工程，越大的工程越需要系统的规划和管理，说白了中国确的不是技术人才，缺的是管理人才，没有优秀的管理者，再多的编程高手都是一盘散沙，各用各的技术，技术无法沉淀下来，当然进步就慢。说实话，我国的编程人才很多，高手也很多，我们的编程人才不比印度少，但是能驾驭管理这些人的人又有多少？体制的确是个大问题 (2002.02.27)

guitarra：中国的管理者就是没眼光，只顾眼前利益
干什么都是一窝蜂 (2002.02.26)

sky_blue：中国有几家软件企业? 大多数时候软件制造者只关心什么时候做出来,根本没考虑怎么才能做好.这其中的差距可大了去了. (2002.02.26)

valhallen 2002-02-27

打赏
举报

微软全球技术中心总经理唐骏以他在微软公司8年的工作经验分析了中国软件企业的不足，他认为，中国软件企业缺乏标准化的研发模式，缺乏了解正规的软件研发流程的管理人员，他们是软件公司的程序经理。他说，在美国，程序经理的地位举足轻重，他们独立于研发部门，专门检查研发部门的开发工作是否符合规定的流程且所有开发工作是否留有完整的文档。印度完全采用美国模式，任用大量从美国回归的人才为程序经理，保证了印度软件研发的标准化和集约化。因此，同一软件的第二代、第三代的开发时间会被几十倍、几百倍地缩短。在中国，同一个软件到了第四代基本上难以避免地要重新写过，反映出软件开发基础工作的薄弱和急功近利。

TechnoFantasy 2002-02-27

打赏
举报

以下是一个详细设计的模板，是我们公司的，但是不同的公司的模板和流程是有差别的。

目录
1 概述 4
2 结构图 4
3 数据结构 4
4 功能模块详细描述 4
5 时间限制 4
6 内存限制 5
7 追溯表 5

1 概述
本章描述详细设计将实现的内容，以及受影响的子系统。假如用了软件图形工具，本章必须包含完整的软件图形模块目录的路径名。
2 结构图
软件系统功能模块的图形描述，它可以让读者对功能模块有一个全面的了解。同时，它也提供了一个有用的索引及一个有意义的调试和维护指南。
数据必须显示在结构图中，同时，流程线应指明模块访问存储区的目的（读、写或修改）。
必须解释所有的用符号表示的内容（包括模块、参数和数据存储区等）。
3 数据结构
· 如果某一数据类型由其它的数据类型组成，要保持信息上的一致性。
· 如果使用一特殊结构，请指明使用原因或优于其它结构的方面。
· 在选择一个有效的结构时，要考虑以下几个方面：
-- 在目标上执行的操作类型
-- 访问目标的类型和频度
-- 结构的有效性
4 功能模块详细描述
首先请简要介绍模块的目的。可以用以下格式描述功能模块的详细设计：
· 模块名称
· 主要功能描述
· 模块的输入参数的名称、数据类型、顺序位置、格式等
· 模块的输出参数的名称、数据类型、顺序位置、格式，以及错误标记等
· 过程和功能调用
· 数据引用（全局，本地，结构）
· 模块的处理流程（采用流程图、判定表辅以必要的说明来表示逻辑流程）
· 模块的界面设计（可以采用图片和表格的形式，具体内容包括：界面格式；界面要素的位置、类型和特殊约定；操作及步骤等必要的说明）
· 接口（用图的形式说明本程序所隶属的上一层模块及隶属本模块的下一层模块，说明参数赋值和调用方式，说明与本程序直接关联的数据结构）
· 限制条件（说明本模块运行所受到的限制条件）
· 伪代码
5 时间限制
如果不需要，可以删除本章。
时间限制仅关系到外部时间。内部时间是一个设计问题。同内存需求一样，时间需求应该在软件生命周期早期决定。然而，执行环境（操作系统，语言等）必然会对时间要求产生一定的影响。详细设计过程引出的时间问题和限制，对高级开发过程是透明的，这些应在本章描述。
例如，在一个实时的多任务环境下，要完成某一特定的任务将会有一个时间限制。
6 内存限制
如果不需要，可以删除本章。
内存需求应该在软件生命周期早期决定。然而，详细设计过程引出的内存问题和限制，应在本章描述。
7 追溯表
详细设计章节概要设计章节软件功能说明书中的需求号

KiteGirl 2002-02-27

打赏
举报

下面是我们SmallFairy的开发文档的格式，供你参考（也不知道算CMM几？）。以一个狐狸养殖场的种系表软件来做例子。

1、软件计划书（语言描述的软件）
关于这个服务于狐狸养殖场的软件的基本需求（养殖场主和设计人员协商。）

2、市场分析（我们就没这个步骤了，因为只有一个客户。）

3、原理设计表（所有用到的基本功能、数据类型、命名方式的规范协议。）
软件的组成：维护、数据库、检索、种系图、自动配对。

4、初级规划书（主要模块的入口、出口、质量要求。）
数据库：插入、删除、移动、修改、追加、初始化……
检索：个体检索（ID、毛色、年龄、性别、品种……）
种系图：双亲种系表（就是找小狐狸的爷爷、姑姑们、舅舅们）
自动配对：自动按照毛色（相似）、品种（相似）、性别（对应）、种系（4代以外）给小狐狸找男（女）朋友。防止近亲繁殖导致退化。

5、结构规划书（模块的结构、质量要求。）
上述功能的具体实现，确定需要的函数、类型等等。

6、细则规划书
每个函数的实现方法、原理。

7、测试计划书
就是研究怎么折磨我们这个可怜的程序。比如出现“我是我祖父（一首幽默歌曲）”现象怎么办？实际当中这个程序就出现了“我是我祖父”问题，而且解决起来相当不容易。

valhallen 2002-02-27

打赏
举报

上面的文档在csdn的2001核定本中就有
我感觉国内绝不缺少code高手
但是毕竟单兵的时代已经过去了那是作坊不是后工业时代的集团化生产
可是我们就是追求code 怪!!
攀比code 不攀比工程以及质量

valhallen 2002-02-26

打赏
举报

1 引言

1.1 编写目的：阐明编写需求说明书的目的，指明读者对象。
1.2 项目背景：应包括
　　● 项目的委托单位、开心单位和主管部门；
　　● 该软件系统与其他系统的关系。
1.3 定义：列出文档中所用到的专门术语的定义和缩写词的愿文。
1.4 参考资料：可包括
　　● 项目经核准的计划任务书、合同或上级机关的批文
　　● 文档所引用的资料、规范等
　　● 列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源

2 任务概述

2.1 目标
2.2 运行环境
2.3 条件与限制

3 数据描述

3.1 表态数据
3.2 动态数据：包括输入数据和输出数据。
3.3 数据库描述：给出使用数据库的名称和类型。
3.4 数据词典
3.5 数据采集

4 功能需求

4.1功能划分
4.2功能描述

5 性能需求

5.1 数据精确度
5.2 时间特性：如响应时间、更新处理时间、数据转换与传输时间、运行时间等。
5.3 适应性：在操作方式、运行环境、与其他软件的接口以及开发计划等发生变化时，应具有的适应能力。

6 运行需求

6.1 用户界面：如屏幕格式、报表格式、菜单格式、输入输出时间等。
6.2 硬件接口
6.3 软件接口
6.4 故障处理

7 其他需求

　　如可使用性、安全保密、可维护性、可移植性等。

valhallen 2002-02-26

打赏
举报

Agent技术文档
－写在1998年耶诞前夕

吃进去的是协议，挤出来的是文档。
——崔健

此文档详细描述了本人作为网络管理小组成员，自1997年年底以来所一直进行着的Agent软件开发工作。

背景知识
在开发Agent软件之前，需熟悉以下内容：
SNMP协议，MIB，ASN.1 SNMP子集，BER编码规则；
UDP协议，无连接Socket编程；
ATM UNI，AAL5；
VxWorks的多任务机制和消息队列机制，及两者的编程；
WRS WindNet软件包的使用和扩展；
Tornado系列开发和调试工具。
以上内容可参阅下述资料：
SNMP，MIB：RFC1155，RFC1157，RFC1122，RFC1213；
ASN.1，BER：X.680，X.690；
有关ATM的书籍，ATM Forum ILMI 4.0；
VxWorks Programmer’s Guide：
Chapter 2：Basic OS
Chapter 5：Network
WindNet SNMPv1/v2c全本
Tornado User’s Guide全本
GNU ToolKit：
The GNU Binary Utilities：ar，ld，nm
GNU Make
编程中若遇到函数调用之类的问题，可参阅
VxWorks 5.3.1 Reference Manual
有关消息队列的介绍另可参考崔健同学的技术文挡。

Agent简述
根据该接入设备的总体设计，网络管理分为用户侧和网络侧两级来进行。每一级的网络管理模块都基于 Client/Server 结构，Manager作为 Client ，以请求的形式向被管对象的Agent（以下简称Agent）发送命令； Agent作为 Server，根据接收到的请求完成相应的操作，并将结果以响应的形式发回给Manager。这两者之间的通信遵循简单网络管理协议（SNMP）。
另外，根据 ATM Forum 制订的规范，用户侧和网络侧的Agent作为 ATM 接口管理实体（IME），两者之间也必须建立起实时对等的通信，每一方都必须实现Manager和Agent的双重功能，既可以以Manager的身份向对方发送请求，也可以以Agent的身份接收和处理对方的请求。两个对等IME之间的通信遵循 ATM Forum 的ILMI 规范（Integrated Local Management Interface Specification）。而 ILMI 也是基于 SNMP 协议之上的。
综上所述，网络管理信息系统 SNMP Agent主要将实现以下功能：
接收和处理来自对应Manager的请求（通过UDP端口）；
两级Agent之间的ILMI 消息传递（通过一个特定的VPI/VCI和AAL5层）；
为实现上述功能而必需的与交换、信令和业务模块之间的消息传递。
图一、二显示了响应实体之间的关系及其协议栈。
上述（3）的功能通过操作系统（采用了实时操作系统 VxWorks）提供的内部通信机制（如消息队列）来实现。而 SNMP Agent的实现则采用了 Wind River System 公司所提供的 WindNet 软件包。
由于 WindNet 只实现了Agent的功能，为了建立起 ILMI 通信，还必须自己实现Manager的功能。

（三）程序及其编译过程的描述
本人编写的程序分成两部分，分放在两个目录下（之所以这样做只是为了尽可能保留WindNet的目录结构）：
$(ATMNET_BASE)/
$(WIND_BASE)/target/src/snmpv1/

程序结构
下图列出了各主要程序之间的依赖关系。上层依赖下层，或者说，位于下层的程序被上层的程序所调用。

下图是Agent各任务间的数据流图： '无图片

（2）$(ATMNET_BASE)/下的程序描述
除了MIB Method Routines（见“$(WIND_BASE)/target/src/snmpv1/下的程序描述”）以外，所有自己编写的C源程序均存放在本目录下，而头文件则放在一级子目录h/下。另外在一级子目录apps/下则存放了在SUN主机上可执行的Manager程序。下面逐一介绍。
Makefile
用来编译和更新网管Agent的程序。
anmadLib.c
Agent的ILMI数据包处理程序，它可能调用snmpMgrLib.c中的SNMP解码程序。
anmaGlobals.c
Agent范围内的全局变量的定义。
anmaIoLib.c
Agent与其他软件模块的消息接口处理程序。
anmaMain.c
在嵌入VxWorks时，Agent软件的唯一入口函数在本文件中定义。
anmInfoLib.c
作为ATM Private MIB的信息源，为后者的Method Routines所调用。
ilmiFsm.c
ILMI 有限状态机的实现。
ilmiInfoLib.c
作为ILMI MIBs的信息源，为后者的Method Routines所调用。
snmpMgrLib.c
为实现Manager功能所编写的例程，主要提供SNMP BER编码和解码函数。其中在解码过程中，如果识别出是Get，Get-next或Set的PDU，说明是对端Manager发过来的数据包，则递交给WindNet的snmpdPktProcess()处理；对于Get-response和Trap的PDU，说明是本地Manager发出请求后得到的响应，则继续全权处理。请同时参阅anmadLib.c。

一级子目录h/：
anmaAll.h
Agent范围内类型和常量的定义，如与其他软件模块通信时所用消息队列的属性和消息的结构，等。
anmaConfig.h
设备配置文件，如设备是node还是user等等。
anmadLib.h
对anmadLib.c中定义的非局部函数的声明。
anmaIoLib.h
对anmaIoLib.c中定义的非局部函数的声明。
anmInfoLib.h
对anmInfoLib.c中定义的非局部函数的声明。
anmPrivMib.h
ATM Private MIB结构类型的定义，类似于$(WIND_BASE)/target/h/snmp/m2Lib.h。
atms_api.h
由交换模块实现的API的声明。这些API主要由网管Agent调用，以完成Manager请求的涉及到交换的操作。
ilmiFsm.h
有关ILMI FSM的类型和常量定义。
ilmiInfoLib.h
对ilmiInfoLib.c中定义的非局部函数的声明。
ilmiMib.h
ILMI MIBs的结构类型的定义，类似于$(WIND_BASE)/target/h/snmp/m2Lib.h。
snmpMgr.h
实现SNMP Manager功能所需要的一些定义，以及snmpMgrLib.c中实现的函数的声明。

一级子目录apps/：
snmpGet.c和可执行的snmpGet
snmpNext.c和可执行的snmpNext
snmpSet.c和可执行的snmpSet
供测试用的能独立运行于UNIX主机上的SNMP Manager程序及其源代码。注意，由于px主机上没有CC和Socket库，编译上述三个程序需在tmn2主机上进行：
tmn2% cc -l socket -I ../h -DUNIX -o snmpGet snmpMgrLib.c snmpGet.c
命令行中，snmpMgrLib.c可根据不同操作系统进行条件编译，所以务请选择-DUNIX或-DVXWORKS。

（3）$(WIND_BASE)/target/src/snmpv1/下的程序描述
凡注明“WindNet”的文件均是WindNet软件包提供的，否则就是本人创建和编写的。在本小节内提到的“Agent”指狭义的SNMP Agent，除此之外，“Agent”均指广义的网管Agent，即本人所做的工作在整个系统中所扮演的角色。

一级子目录agent/：
Makefile
用来编译和更新WindNet。
snmpIoLib.c（WindNet）
SNMP Agent I/O，包含了 snmpIoInit()，，snmpIoClose()，snmpIoMain()，snmpIoBody()，snmpIoCommunityValidate()等函数，可根据实际情况修改，特别是snmpIoWrite()和snmpIoCommunityValidate()，一定要做相应的配置。这些函数的具体描述请参阅WindNet SNMPv1/v2c，P47）。
snmpMib2.mib（WindNet）
MIB2的控制文件，决定MIB Method Routines的函数名等。控制MIB主要用到三个关键字：FORCE-INCLUDE，DEFAULT，EXCLUDE，具体用法请参阅WindNet SNMPv1/v2c，P80：mibcomp Extensions。
ilmiMib.mib
ILMI MIBs的控制文件。
anmPrivMib.mib
ATM网管自定义MIB的控制文件。
snmpMib2.c，mibhand.h，mibleaf.h
mibcomp的生成文件，snmpMib2.c定义了MIB的内部存储格式，mibhand.h是对Method Routines的声明，mibleaf.h是对MIB常量的定义。

二级子目录agent/anm_rtns：
二级子目录agent/ilmi_rtns：
二级子目录agent/snmp_rtns（WindNet）：
各个MIB的Method Routines，每个文件对应于一个Group。在写这些函数时，可先用mibcomp -stub生成.c文件，再在此文件上做修改，这样可省却许多录入工作。

一级子目录rfc_mibs/（WindNet）：
标准的RFC MIBs，如rfc1213.mib等。

一级子目录anm_mibs/：
ILMI MIBs，ATM Private MIB等与ATM相关的非RFC MIBs。

（4）在开发阶段编译Agent的一般步骤
环境：主机为tmn2，WindNet源程序也在tmn2上；
当前用户为wrs，这是专为调试而建立的用户；
目标机为mv162，其CPU为MC68LC040。
设置环境变量：
% source ~wrs/.cshrcsnmp
.cshrcsnmp是本人建立的一个配置文件，定义了有关SNMP的环境变量和mibcomp、cc68k的一些常用选项。它不是系统的缺省文件，所以需要手动执行。.cshrc才是系统的缺省配置文件，在用户登录时自动执行。
编译WindNet：
% cd ~wrs/wind/target/src/snmpv1/agent
% make CPU=MC68LC040 TOOL=gnu
此举将编译本目录下Makefile中所列出的相关文件，make的结果是得到最新版本的~wrs/wind/target/lib/libMC68LC040gnuvx.a
配置和编译vxWorks：
% launch&
（如果是开机后第一次运行Tornado的调试工具，则执行 source ~wrs/startit&）
选择target server：mv162@tmn2；
（如果该target server不存在，请先创建它，target server的配置如下：
tgtsvr <target_IP> -A -V -n mv162 -B wdbrpc -f a.out
具体的用法请参阅Tornado User’s Guide：The Tornado Launcher，P105）
在launch面板上选择WindCFG，在随后打开的配置窗口依次选择mv162lc，windNet，注意必须有以下两项内容：
#INCLUDE_MIB2_ALL
#INCLUDE_SNMPD
在上面打开的配置窗口中依次点击Config按钮和Build按钮，开始编译vxWorks内核。
重新启动目标机。
编译其它Agent程序：
在$(ATMNET_BASE)/目录下运行make，将最终的目标文件下载到目标机调试。

（5）在开发阶段扩展MIB的一般步骤
用ASN.1编写MIB。如果要实现已有MIB中被控制MIB EXCLUDE掉的Group，则将相应的EXCLUDE语句注释掉。
写Method Routines。这可能会涉及到修改或创建以下三个文件：xxxMib.h，xxxInfoLib.h，xxxInfoLib.c，其中xxxMib.h是该MIB的类型和常量定义，xxxInfoLib.c为method routines提供支持，是后者的信息来源。
在~wrs/wind/target/src/snmpv1/agent/目录下的Makefile中OBJS一项增补相应的.o文件。
make。见前述“在开发阶段编译Agent的一般步骤”（a）~（d）。