我的程序员守则

我的程序员守则

作者：    Fox

时间：    2003-12-9

版本：    初稿

1       总则

本文描述的是作者从软件开发的实践过程中摸索出来的一些经验准则。

 

通过对照这些准则，本人可以在软件开发的过程中，对自己的日常行为经常作出自我评价和检讨，以达到提高软件质量和编写软件效率之目的。

 

本文为初稿，以后版本会对新的想法进行补充或者对已有的不足部分进行修改。

本文希望对程序员同仁们也有所帮助。

2       细则

2.1    编码规范

软件代码的易读性对于软件的协作开发和发布以后的维护具有重要的意义，同时代码的“漂亮程度”也反映出了一个程序员的编码水平。

2.1.1   命名规则

命名包括类名、函数名、变量名等。

命名不要用人名和汉语拼音。命名要能体现出相应变量或函数的意义。

 

命名规则主要有匈牙利命名法和Unix/Java命名法（具体名字我记不清了：），前者常用于Windows程序代码中，而后者则在标准C程序或Java程序中。

 

前者的缺点是命名看上去不是很清晰，大小写混在一起；优点是含意非常清楚，甚至某变量是什么类型都可从名称上直接看出来。

 

匈牙利命名的规则细节请参见附录。

2.1.2   代码缩进

代码要对齐，做到层次分明。这是决定代码清晰与否的重要因素。

 

现代的专用编辑器对代码的排版都具有很好的智能处理，例如MS VC++就是一个很不错的选择，其默认排版基本上可以保证代码的自动缩进。

 

Tab的宽度设为4个空格的宽度，但仍然保留Tab字符，不要用空格代替。

 

小技巧：如果您的代码由于某些原因层次缩进变得非常糟糕，您不用担心。您可以在VC++的编辑器中，选中要格式化的代码，然后按ALT+F8即可。

2.1.3   注释

注释一般有两种方式：C语言中的传统注释方法（/*注释*/）和C++的注释方法（//注释）。

 

前者适合于大块的代码注释，而后者适合单行的注释。

前者最大的缺点就是不支持嵌套注释，否则会产生编译错误；而后者对于大块的注释需要每行都加上“//”，略显麻烦。不过VC7以上的版本支持了同时对多行代码进行“//”方式的注释，或者使用Visual Assist这个工具也可。

 

注释按位置可分为代码内注释和文档注释。代码内注释不要求太多，但要说明某一块的功能，某些细节的难点和疑点，代码本身就能明显表达的功能就不要再重述了。文档注释主要包括开发文档及对接口的描述文档。

2.1.4   代码分布

一个模块（以C++为例，由{}构成的部分）不要超过50行；一个函数不要超过100行；一个源文件最好不要超过1000，最多不能超过5000行。

 

一个相对独立的项目应该有一个工作空间（VC6为.dsw文件）或解决方案（VC7中为.sln文件），其中可以包含多个工程（.prj、.dsp或 .vcproj）。一个.h和.cpp包含一个类，对于关系很密切的几个类，或者一个类只是为另外一个类使用，则也可以放在一个源文件中。

 

对于OOP，除非迫不得已，不要出现全局变量和全局函数，这是OOP的基本要求。

2.2    文档规范

文档应该加入CVS中，单起一个目录。包括设计文档、开发文档、用户手册等。另外规范文档也可以作为一个目录，作为程序员日常行为的准则，例如本文。

 

做到需求和设计的文档化及文档书写的规范，即不仅仅是给最终用户看的使用文档。

 

若在Windows下编写程序，文档统一采用Word的.doc格式。注意，加入CVS要使用二进制格式。

 

文档命名规则：“日期_标题_作者_版本.doc”，如“031209_程序员守则_Fox_1_0.doc”，不过加入CVS的文档应把日期和版本去掉，即“标题_作者.doc”，如“程序员守则_Fox.doc”，因为CVS本身就会记录日期和版本。

2.3    代码管理/版本控制

2.3.1   管理工具

代码管理工具主要有MS Visual SourceSafe和CVS（WinCVS）。推荐使用后者。

2.3.2   注意事项

每天工作之前更新（Update）CVS，下班时提交CVS，提交（Commit）之前应再次更新，减少冲突的可能性。提交代码的必须是编译通得过的。每次提交都要在注释栏注明修改的原因，供日后和其他程序员查看。

 

不需要加入CVS的文件有：可以由CVS中代码编译生成的文件、集成环境根据用户偏好生成的文件等。但是由第三方提供的.lib或.dll文件应加入CVS中。总之要保证代码的完整性，做到“不重不漏”。

2.3.3   目录分层

目录分层：先按项目分块，然后按H, Lib, Source的目录结构分。

2.3.4   版本管理

每出一个Release版，都要在CVS中打上Tag，以便以后随时可以把它重新拿出来。

公共库的使用和维护。

2.3.5   使用Nightly Build

Nightly Build技术和CVS结合可以自动完成对某个版本的获取、编译、链接和测试整一套过程。特别是对于代码量达几十万行以上的大型项目，人工干预以上过程会显得非常繁琐且容易出错，使用Nightly Build可以帮助我们解决此问题。

2.4    BUG跟踪

Bug跟踪（Bug Tracking）是软件开发过程中的一重要环节，而且需要专门的软件测试工程师（Software Test Engineer）来对编码已经基本完成的软件进行测试。

 

Bug跟踪有很多免费的工具可以在网上下载使用，多数是基于Web的，方便很多人员同时参与。

 

Bug跟踪的流程：测试人员发现并提交Bugà软件工程师修复并/或反馈Bugà测试人员确认Bug已修复à管理员冻结或结束已确认已修复的Bug。

2.5    软件工程/项目设计

软件工程的几个环节：计划、编码、测试、维护等。

2.5.1   计划

每个项目开工之前都要有个周密的计划，软件工程也不例外。计划主要分为需求分析、功能设计、工作量估计、时间进度安排及模块划分等阶段。

 

软件计划是软件工程的关键环节。“良好的开端是成功的一半”，好的需求分析、进度安排是整个项目成功的重要因素。

 

计划占整个软件工程周期的1/3。

2.5.2   编码

（详情请见上面相关章节。）

纯粹编码的时间并不多，约占整个软件工程周期的1/6。

2.5.3   测试

测试按范围可分为单元测试和集成测试；按性质分为白盒测试和黑盒测试。

 

单元测试很重要，不能忽略，往往有些问题在集成测试阶段发现或很难找到解决问题的入口，往往都是单元测试没有做好。集成测试是对把各个模块整合的整个系统进行测试，主要测试系统功能和性能。

 

白盒测试主要是在程序员内部进行测试，拥有源代码，可以对代码进行一些修改以更好的发现Bug和定位引起Bug的代码。黑盒测试可以由测试人员甚至是最终用户进行，建立专门的网站（Bug跟踪系统）进行问题的反馈。

测试占整个软件工程周期的1/4。

 

温馨提示：

测试的产品应该使用Debug版本，因为debug版本包含调试信息，可以方便Bug定位。

在代码中适当的使用ASSERT，检验参数或者条件的合法性，可以较早的发现一些Bug，减轻测试的一部分压力。

2.5.4   维护

维护确实是一件非常棘手的事情。在测试阶段没有发现的Bug修复、用户对需求的变更等，都会是比较长的时间，事实上维护占了整个软件周期的1/4的时间。这时软件维护的难易程度、代价高低，很大程度体现出前期软件设计需求分析的好坏和编码质量、软件伸缩性能的优劣。

2.6    团队建设

一个好的产品需要有一个好的团队，好的团队需要有好的团队建设。好的团队建设，可以使人振奋人心，激发团队成员的积极性和创造力。

 

团队建设主要包括：对人员的选择、人员的培训、任务的分配及业余时间的集体活动等。很重要的一点，体现在工作和生活上的组员之间的相互关心，可以给团队成员一个温馨、舒适、放松的环境。

2.7    环境配置

公司或工作室设置一个域，其中每台计算机都加入该域中，统一管理。每个项目组为域中的一个组，项目组员为域组中的用户。每个组员分配一台固定的计算机。

 

域名可以取成公司的名称。每台计算机分配一个网内IP和一个和组员相对应的计算机名称，方便其他用户查找。另外还须配置一台可以直接连到网外的计算机，其他计算机通过它上网。此代理服务器最好要和域控制器分开。

 

此外，还需有一台计算机，用来存放共享数据，如常用工具、数据备份等。至于用户认证等安全问题，我们可以通过配置域的方法来解决。

3       附录

3.1    命名规则——匈牙利命名法

3.2    WinCVS使用手册及CVS命令速查手册

3.3    Bug跟踪系统简介

3.4    优秀代码示例

3.5    优秀文档示例