UFQP2-09QI004 JAVA程序编程规范（代码与注释）

文件编号:UF/QP/2-09/QI/004 审核:SEPG日期:01/10/25版号:1.0页号:5/5PAGEPAGE12024代码与注释书写风格规范代码书写风格规范必须给程序加注释。注释能够极大提高代码的质量。代码的书写必须清晰、易读。适当的将代码分段可以使代码更加清楚。可以使用‘{’‘}’将函数分成若干个小的单元；适当的加入空行可以使代码更加清晰。例如在函数的定义后面加入两个空行，在两个逻辑小代码单元间加入一个空行；建议遵循三十秒原则。如果另一个程序员无法在三十秒之内了解你的函数做了什么，如何做以及为什么要这样做，那就说明你的代码是难于维护的，必须得到提高；在一个函数内代码的长度不允许超过100行。建议如果一个函数的代码长度超过一个屏幕，那么或许这个函数太长了。一行代码尽量简短，并且保证一行代码只做一件事。那种看似技巧性的冗长代码只会增加代码维护的难度。保证不必左右拉动滚动条来阅读一整行代码，将会使你的代码更加可读，这一点包括注释；使用圆括号来界定操作的顺序。不要让别人判断复杂的操作优先级。使用统一的格式化代码。将‘{’放在所有者的后面，并且在下一行代码前加入TAB键缩进；（TAB键比用若干个空格更容易控制使用统一的缩进距离）if(XXX){while(XXX){xxxxxx}}注释书写风格规范注释总规则注释应该用中文清晰表达意思。应该能够使程序看起来更清晰，更容易理解。如果某一段程序不值得写文档，那么可能它是无效的代码。注释要尽量简明，避免装饰性的、标语式的注释。注释不但要说明做什么，还应当说明为什么要这样做。最好先写注释表明要做什么，再进行编码。另起一行的注释，要写在被注释程序的上一行。类的注释类型的用途、目的。包括其它别人可能感兴趣的介绍；已知的Bug。当然最好是修正所有的错误，但是有时可能暂时还没有办法修正错误，或暂时没有时间精力去修改；开发和维护该类的历史列表。记录每一次修改的作者、日期、修改的内容；列举类的各种稳定状态。说明调用成员函数使类的状态产生的变迁；同步问题。对主要的算法必须加以解释说明，主要的流程必须给出引导性的说明。标准格式：/***描述类的功能、用途、现存BUG，以及其它别人可能感兴趣的介绍。*作者：XXX*@version 最后修改日期*@see 需要参见的其它类*@since 从产品的那一个版本，此类被添加进来。（可选）*@deprecated该类从产品的那一个版本后，已经被其它类替换。（可选）*/如果对已经版本话的类进行了修改，需要按照如下格式为每一次修改附加修改历史记录： //修改人+修改日期 //修改说明范例： /** *MessageDispatcher的主要功能是将消息源传来的各种消息，分发给相应的消息*处理器进行处理。*作者：张三*@version 2000/04/20*@see UFMessage,Event *@deprecated 从NC-1.0版之后该类的功能被EventDealer取代，但为了保持* 向下兼容性，此类仍然被保留*///李四2000/05/21//添加了对帮助信息的处理函数sendToHelpManager(UFMessagemsg)。 //王小二2000/06/02//修改了不能正确定位用户消息的错误。接口的注释接口的注释风格基本与类的注释风格相同。在别人使用接口之前，必须了解接口所包含的概念。检验一个接口是否应该定义的简单方法是：你是否能够容易的描述接口的用途。接口如何应当和不应当被使用。开发者需要知道该接口如何被使用，也希望知道该接口不能被怎样使用。函数的注释函数头注释必须包括：函数执行了什么功能，为什么要这样处理；函数处理过程中对对象的那些属性可能进行更改；函数执行前后，对象的状态。比较、循环等控制结构必须加注释；在代码的功能并非一目了然的情况下，应当说明为什么要这样做；局部变量必须加注释；复杂难写的代码必须加注释；如果一系列代码的前后执行顺序有要求，必须注释说明。函数头注释标准：/***描述函数的功能、用途、对属性的更改，以及函数执行前后对象的状态。*@param 参数说明*@return 返回值*@exception异常描述*@see 需要参见的其它内容*@since 从类的那一个版本，此方法被添加进来。（可选）*@deprecated该方法从类的那一个版本后，已经被其它方法替换。（可选）*/范例：/***将消息转发给帮助管理器，显示对应的帮助内容。*@param msgierp.sm.core.eo.UFMessage消息的内容*@return ierp.lang.boolean帮助管理器是否正确接收到消息。*@exceptionjava.lang.NullPointException如果消息为NULL抛出此异常。*@see ierp.sm.core.eo.UFMessage*@since 从NC-0.8版该方法被添加。*/类属性的注释描述域的用途。使别人知道如何去使用它；注释对变量的固定限制。例如dayOfMonth域就应该注明它的值在1-31之间。通过注释对域的限制，帮助你定义重要的事物规则，也使别人更加容易理解你的代码；对于有着复杂事物规则的域，可以加入范例来说明。有时候一个简单的小例子，抵的上千言万语；必须理清，并且清楚的注明并发问题。并发错误是很难在调试和维护阶段发现和排除的；局部变量的注释每行只声明一个局部变量，并且在行末加入注释；注释的参考内容为说明该变量被什么、在那里、为什么使用；附录匈牙利命名法前缀对应表基本变量变量类型前缀范例byte,short,int,longnnCountFloatffTotalDoubleddSumCharccTempBooleanbbEndOfLinearrayaryaryEmployees常用工具类变量类型前缀范例StringstrstrNameVectorvecvecPackageHashhashhashContainerStringBuffersbsbSourceObjectobjobjData常用控件控件类型前缀范例ButtonbtnbtnOKTextFieldtftfNameTextAreatataNoteCheckBoxckbckbShowAllRadioButtonrbrbSexListlistlistDepartmentComboBoxcbbcbbWorkCenterLablelblbAddressTabletbtbItemsTreetrtrAccountProgressBarpbpbMRPPanelpnlpnlVoucherScrollPanescpscpPictureTabbedPanetbptbpMainDialogdlgdlgTipFramefrmfrmDesktopMenumnmnHelp说明：在可视化环境当中，由于VisualAge会在每一个控件的命名前加上小写的ivj前缀，所以在设置控件的BeanName属性时，需要将上表中的前缀的第一个字母大写。如：BtnCancel对于未定义标准前缀的类可以按照以下原则使用前缀：由一个单词构成类名，可以将这个类名全部小写（或者先缩写），作为前缀，在后面再加上表明用途含义的说明性修饰。如：Employee employeeRetiredMail mailUnread由多个单词构成的类名，可以取每个单词的首字母组成缩写组合（根据情况可以添加若干体现单词发音的字母），作为前缀。注意不要与标准前缀重复。WorkCenter wcAvailableDefautMessageEvent dfmeReceived常用动词表汉语含义英文单词或缩写范例做某事dodoQuery设置setsetName取得getgetName审核checkcheckVoucher增加addaddEmployee修改modifymodifyContent删除delete,remov