SVN软件开发日志规范

SVN SVN软件开发日志规范

前言：
写代码的好习惯除了言简意赅的注释外，还有完善且必要的日志。注释主要是对代码内的模块或功能函数、算法、逻辑框架等进行必要简明的说明，它关注的是”这个“代码里做了什么。而日志需要说明的是这版代码和上一版本改了什么（重点关注代码的升级迭代、用途、风险），和其他代码有啥关系（比如关注是否某些功能模块借鉴或移植于其他项目）。所以日志主要关注的是“这些”代码之间的关系（改动、移植），以及怎么用它，有何风险。所以不要觉得代码里写了足够的注释就不需要写Log了，经验丰富的软件开发们会形成自己完整的一套规范风格。

1 如何写代码日志？

这是我们要回答的第一个问题。通过上面的简介我们大致知道代码Log需要记录哪些信息了，但是这还不够。做软件一个很重要的思维方式就是把问题分类或分块进行细化。一版代码按照开发的进程分，可以分为首次开发和变更开发。按照软件发布的用途分，可以分为临时程序（用于新方案实验、辅助硬件测试、给客户送样等）和受控程序（指正式出货的程序）。按照发布次数可以分为初版发布和变更发布（程序升级）。另外还可以根据自己特色进行分类，比如按所用芯片型号、平台、开发语言、内部开发或内外合作。你的日志里要能清晰分辨出来现在在做的是属于哪一类程序。

2 先弄清楚现在要写的是什么程序

当项目立项时,我们第一步当然是仔细阅读相关文档（可能是设计开发要求、方案策略设计说明、设计变更通知单、产品立项报告等等，不同的公司会有较大的差异，当然有些公司没有任何文档，全靠嘴（我这经历过什么。。。））。这些文档里除了告诉我们需要做出什么样功能的程序外，我们还能知道这是一个新项目还是老项目升级，这是将来要正式出货的程序还是只是实验程序。如果是老项目程序升级，那它就一定存在历史版本，且应该清楚的知道改动了什么。如果是正式出货的程序，那它一定有适用范围，比如这版程序用于哪些型号，哪些芯片或平台，甚至应该有对应的硬件版本号（当然，当硬件电路做出改动时软件需要评估是否能兼容，这种问题比较多发生在嵌入式行业，互联网行业就是所用的架构和平台版本了）。如果是临时程序，一定要把它区别于正式程序，写明程序的意图和提供给了谁，特别是做了某些实验验证后会得出一些进展结果，能说明的尽量说明。
开发一版程序往往不可能SVN只上传一次就成功，开发过程中，每天下班前上传新代码并写上Log是一个好习惯，这种情况需要简明的写上代码改动点和遗留问题，方便下一次开发能快速衔接。

3 未发布软件Log模板

--------------------------------代码开发----------------------------------------------
工程名：（写这个并不重复，因为工程名后期可能会改（虽然几乎不会），每个日志都写方便追溯。）
软件版本：（如：200305 V1.0）
带上版本号后发布，不允许对已发布出去的备份程序做任何修改。）
上传修改：（首次上传/修改上传。）
版本迭代：（初版/在某某版本上变更升级。）
上传人：（还是建议给自己取个英文名吧。）
上传时间：（比如用六位日期数字200303，别想了，下个世纪你的程序早被淘汰了。）
上传原因：（如果是首次上传就写明开发目的，如：某某项目生产出货、用于某实验、给某客户送样等，如果是开发过程中的修改上传就写开发上传。）
修改点：（这个很重要，要做到描述简明但不漏点，就是说改动了哪几个大方向要一个不漏，但是这些方向细节改了什么这里只用简明概括，想了解细节的时候对比代码就行了，当然代码内注释要写好。）
遗留问题：（如果是在开发过程中的修改上传，写明还未进行和还未完成的功能，以便下次继续开发。如果是已经发布的程序，写明软件的风险点，方便未来软件升级时优化或排查Bug时更快定位问题。如果暂未发现风险点则写未知。）
适用范围：（在这里写明用于什么芯片或平台。用了什么开发工具（有些大公司比较统一，而且万年不升级工具，一般小公司比较乱，不同的人用不同版本的IDE，甚至不同的开发语言。适用于哪些项目，写上项目名。总之限制软件通用性的条件可以写在这里。）
* 使用芯片：
* 硬件版本：
* 适用项目：
* 适用协议：
工具平台：（在这里写上所用开发工具或平台的版本。）
* 底层库版本：
* 编译器：
* 离线编程器上位机：
其他描述：（需要提示或强调的东西，比如和某第三方公司合作开发，分别负责什么模块之类的。）

4 软件发布时应该写什么Log

像前面的开发日志主要是写给软件开发人员看的，而发布出去的程序供给外部门，他们不需要知道太多软件修改的细节，主要需描述清楚3点：1、这版软件实现了哪些功能。2、适用范围。3、风险点有哪些。发布日志还有一个重要的信息，就是版本的升级迭代关系。这版软件是用于替换哪版旧软件，还是初版软件，这一点也可以归类到适用范围里。一些大公司有完善的流程管理平台（比如JIRA等），相关的信息详细记录在平台上。对于一些未搭建平台的小公司建议在工程里创建一个文档，随着开发过程保持文档更新。这份文档在最终出货时可以做成软件适用说明文档给出去。

5 已发布软件Log模板

--------------------------------软件发布----------------------------------------------
发布软件名：（要发布的是软件名称，名称里要带上软件版本号。）
软件版本：（如：200305 V1.0）
项目当前状态：（完成/进行/暂停/废止）
发布目的：（用于某项目产品生产出货/用于某项实验/）
版本特征：（正式出货的为受控版，对其有严格的管控，其他为临时版，比如用于测试或验证，管控可能不严格。）
版本迭代：（初版/在某某版上修改）
发布人：
发布时间：
功能描述：（列举出该版软件已经实现的功能，重点描述设计开发要求上提到的功能的实现情况。只写实现了没有，不要在这里啰嗦描述为什么没有实现原因等。）
变更原因：（如果是旧版基础上变更则写明变更原因。若为初版则写初版即可。）
变更点：（变更程序简明写变更点（这里不要写详细的软件修改点，从前后两版的功能角度写解决了什么Bug或做了什么优化。若为初版则写初版即可。）
适用范围：（在这里写明用于什么芯片或平台。用了什么开发工具（有些大公司比较统一，而且万年不升级工具，一般小公司比较乱，不同的人用不同版本的IDE，甚至不同的开发语言。适用于哪些项目，写上项目名。总之限制软件通用性的条件可以写在这里。）
* 使用芯片：
* 硬件版本：
* 适用项目：
* 适用协议：
测试情况：（通过测试/未通过测试）
遗留问题：（写明风险点，如果暂未发现风险点则写未知。）
工具平台：（在这里写上所用开发工具或平台的版本。）
* 底层库版本：
* 编译器：
* 离线编程器上位机：
其他描述：（需要提示或强调的东西，比如和某第三方公司合作开发，分别负责什么模块之类的。）

6 如何写文档日志？

上面已经讨论过如何给代码写上日志，在开发过程中一个软件开发人员会接收和产出很多文档，这些文档都需要和项目相关联并并在SVN等平台做好记录并上传，也会设计到Log的编写。一般来说文档的Log相对显得不那么重要，只需在日志里说明上传的文档里包含了哪些信息，属于哪个项目，文档修改时简略说明文档的修改点。当然比较重要的信息比如调试测试报告测出Bug或发现风险时，也请在Log里简明描述下。有些公司会按照文档的类别进行分类Log，比如调试测试报告的Log规范和软件其他文档Log规范不同，这里我只介绍通用简单的模板。

7 文档Log模板

--------------------------------文档上传----------------------------------------------
上传修改：（首次上传/修改上传。）
上传人：
上传时间：
上传原因：（比如：某某项目某版软件设计开发要求。某某项目某版软件调试报告。流程规范化软件则写软件规范化实施说明管理文档。等等。）
修改点：（简明写文档做了哪些改动，如果第一次上传就写首次上传。）
其他描述：（需要提示或强调的东西，比如调试测试报告里发现的Bug或风险点。）

实际这个规范不仅可用于SVN规范也能套用到其他平台和部门。