荔园在线
荔园之美，在春之萌芽，在夏之绽放，在秋之收获，在冬之沉淀
[回到开始]
[上一篇][下一篇]
发信人: Deny (孤苦伶仃一个人，哈哈), 信区: Program
标 题: 编码规则
发信站: 荔园晨风BBS站 (Tue Dec 25 20:05:52 2001), 转信
介绍
关于编码规则
正文
目 录
第 一 部份 VB源代码编码约定 3
1. 1 为什么要进行编码约定？ 3
1. 2 最小编码约定 3
1. 3 对象命名约定 4
1. 4 常量和变量命名约定 7
1. 5 结构化编码约定 9
1. 5.01 代码注释约定 10
1. 5.02 记住下列几点： 10
第 二 部份 Java编码规范 13
2. 1 简 介 13
2. 2 格 式 13
2. 2.01 缩进 13
2. 2.02 间隔 15
2. 2.03 空行 17
2. 2.04 类成员的摆放顺序 17
2. 2.05 文件格式(File Format) 17
2. 2.06 行最大长度 18
2. 2.07 括号 18
2. 3 标识符 18
2. 3.01 类和接口 19
2. 3.02 包 19
2. 3.03 其它标识符 19
2. 3.04 get和set方法 20
2. 4 注 释 20
2. 4.01 JavaDoc 20
(a) 类 22
(b) 方法 24
2. 4.02 代码的自我说明 24
2. 5 编 码 27
2. 5.01 决不要使用的结构 27
(a) 决不要使用do…while结构 27
(b) 决不要在一个方法的中间使用“return” 28
(c) 决不要用“continue” 28
(d) 决不要使用“break”，除非是转换状态（switch statement）控制
28
2. 5.02 不要混合使用递增运算符和递减运算符 29
2. 5.03 初始化 29
2. 5.04 范围（scope） 30
第 三 部份 Java编程规则 31
第 一 部份 VB源代码编码约定
1. 1 为什么要进行编码约定？
使用统一编码约定集的主要原因，是使应用程序的结构和编码风格标准化，以便于
阅读和理解这段编码。
好的编码约定可使源代码严谨、可读性强且意义清楚，与其它语言约定相一致，并
且尽可能的直观。
1. 2 最小编码约定
一组通用目的的编码约定应该定义完成上述目的所必需的、能让程序员自由地创建
程序逻辑和功能流程的最小的要求。
最小编码约定的目的是使程序易于阅读和理解，而不是用过份的约束和绝对的限制
来束缚程序员本身的创造性。
所以，该附录中提出的约定是简洁和建意性的。这些约定中没列出每一个可能的对
象或控件，也没列出每种有用的信息注释。根据工程及机构的特殊要求，也许希望
扩充这些准则，以包含附加的元素，如：
对于在家庭中开发的或从第三方厂商购买的特定对象及组件的约定。
描述机构的商业活动或设备的变量。
工程或企业认为对清楚性和可读性很重要的任何其它元素。
1. 3 对象命名约定
应该用一致的前缀来命名对象，使人们容易识别对象的类型。下面列出了
Visual Basic 支持的一些推荐使用的对象约定。
推荐使用的控件前缀
控件类型 前缀 例子
3D Panel pnl pnlGroup
ADO Data ado adoBiblio
Animated button ani aniMailBox
Check box chk chkReadOnly
Combo box, drop-down list box cbo cboEnglish
Command button cmd cmdExit
Common dialog dlg dlgFileOpen
Communications com comFax
Control （当特定类型未知时，在过程中所使用的） ctr ctrCurrent
Data dat datBiblio
Data-bound combo box dbcbo dbcboLanguage
Data-bound grid dbgrd dbgrdQueryResult
Data-bound list box dblst dblstJobType
Data combo dbc dbcAuthor
Data grid dgd dgdTitles
Data list dbl dblPublisher
Data repeater drp drpLocation
Date picker dtp dtpPublished
Directory list box dir dirSource
Drive list box drv drvTarget
File list box fil filSource
Flat scroll bar fsb fsbMove
Form frm frmEntry
Frame fra fraLanguage
Gauge gau gauStatus
Graph gra graRevenue
Grid grd grdPrices
Hierarchical flexgrid flex flexOrders
Horizontal scroll bar hsb hsbVolume
Image img imgIcon
Image combo imgcbo imgcboProduct
ImageList ils ilsAllIcons
Label lbl lblHelpMessage
Lightweight check box lwchk lwchkArchive
Lightweight combo box lwcbo lwcboGerman
Lightweight command button lwcmd lwcmdRemove
Lightweight frame lwfra lwfraSaveOptions
Lightweight horizontal scroll bar lwhsb lwhsbVolume
Lightweight list box lwlst lwlstCostCenters
Lightweight option button lwopt lwoptIncomeLevel
Lightweight text box lwtxt lwoptStreet
Lightweight vertical scroll bar lwvsb lwvsbYear
Line lin linVertical
List box lst lstPolicyCodes
ListView lvw lvwHeadings
MAPI message mpm mpmSentMessage
MAPI session mps mpsSession
MCI mci mciVideo
Menu mnu mnuFileOpen
Month view mvw mvwPeriod
MS Chart ch chSalesbyRegion
MS Flex grid msg msgClients
MS Tab mst mstFirst
OLE container ole oleWorksheet
Option button opt optGender
Picture box pic picVGA
Picture clip clp clpToolbar
ProgressBar prg prgLoadFile
Remote Data rd rdTitles
RichTextBox rtf rtfReport
Shape shp shpCircle
Slider sld sldScale
Spin spn spnPages
StatusBar sta staDateTime
SysInfo sys sysMonitor
TabStrip tab tabOptions
Text box txt txtLastName
Timer tmr tmrAlarm
Toolbar tlb tlbActions
TreeView tre treOrganization
UpDown upd updDirection
Vertical scroll bar vsb vsbRate
推荐使用的数据访问对象 (DAO) 的前缀
用下列前缀来指示数据访问对象。
数据库对象 前缀 例子
Container con conReports
Database db dbAccounts
DBEngine dbe dbeJet
Document doc docSalesReport
Field fld fldAddress
Group grp grpFinance
Index ix idxAge
Parameter prm prmJobCode
QueryDef qry qrySalesByRegion
Recordset rec recForecast
Relation rel relEmployeeDept
TableDef tbd tbdCustomers
User usr usrNew
Workspace wsp wspMine
一些例子：
Dim dbBiblio As Database
Dim recPubsInNY As Recordset, strSQLStmt As String
Const DB_READONLY = 4 ' 设置常量。
'打开数据库。
Set dbBiblio = OpenDatabase("BIBLIO.MDB")
' 为SQL 语句设置文本。
strSQLStmt = "SELECT * FROM Publishers WHERE _
State = 'NY'"
' 创建新的记录集对象。
Set recPubsInNY = db.OpenRecordset(strSQLStmt, _
dbReadOnly)
推荐使用的菜单前缀
应用程序频繁使用许多菜单控件，对于这些控件具备一组唯一的命名约定很实用。
除了最前面 "mnu" 标记以外，菜单控件的前缀应该被扩展：对每一级嵌套增加一
个附加前缀，将最终的菜单的标题放在名称字符串的最后。下表列出了一些例子。
菜单标题序列 菜单处理器名称
File Open mnuFileOpen
File Send Email mnuFileSendEmail
File Send Fax mnuFileSendFax
Format Character mnuFormatCharacter
Help Contents mnuHelpContents
当使用这种命名约定时，一个特定的菜单组的所有成员一个接一个地列在
Visual Basic 的“属性”窗口中。而且，菜单控件的名字清楚地表示出它们所属
的菜单项。
为其它控件选择前缀
对于上面没有列出的控件，应该用唯一的由两个或三个字符组成的前缀使它们标准
化，以保持一致性。只有当需要澄清时，才使用多于三个字符的前缀。
例如，对于派生的或修改的控件象上述那样扩展其前缀，使得在真正使用了哪一个
控件的问题上避免混淆。对于第三方控件，应该把制造商的小写缩写名附加到前缀
中。例如，从 Visual Basic Professional 3D 框架中创建的一个控件实例可以用
fra3d 这样的前缀，以避免混淆所使用的控件。
1. 4 常量和变量命名约定
除了对象之外，常量和变量也需要良好格式的命名约定。本节列出了 Visual
Basic 支持的常量和变量的推荐约定。并且讨论标识数据类型和范围的问题。
变量应该总是被定义在尽可能小的范围内。全局 (Public) 变量可以导致极其复杂
的状态机构，并且使一个应用程序的逻辑非常难于理解。全局变量也使代码的重用
和维护更加困难。
Visual Basic 中的变量可以有下列范围：
范围 声明位置 可见位置
过程级 过程，子过程或函数过程中的 ‘Private’ 在声明它的过程中
模块级 窗体或代码模块（.frm、.bas ）的声明部分中的 ‘Private’ 窗体或代
码模块中的每一个过程
全局 代码模块（.bas）的声明部分中的 ‘Public’ 应用程序中的每一处
在 Visual Basic 的应用程序中，只有当没有其它方便途径在窗体之间共享数据时
才使用全局变量。当必须使用全局变量时，在一个单一模块中声明它们，并按功能
分组。给这个模块取一个有意义的名称，以指明它的作用，如 Public.bas。
较好的编码习惯是尽可能写模块化的代码。例如，如果应用程序显示一个对话框，
就把要完成这一对话任务所需要的所有控件和代码放在单一的窗体中。这有助于将
应用程序的代码组织在有用的组件中，并减小它运行时的开销。
除了全局变量（应该是不被传递的），过程和函数应该仅对传递给它们的对象操作
。在过程中使用的全局变量应该在过程起始处的声明部分中标识出来。此外，应该
用 ByVal 将参数传递给 Sub 过程及 function 过程，除非明显地需要改变已传递
的参数值。
变量范围前缀
随着工程大小的增长，划分变量范围的工作也迅速增加。在类型前缀的前面放置单
字母范围前缀标明了这种增长，但变量名的长度并没有增加很多。
范围 前缀 例子
全局 g gstrUserName
模块级 m mblnCalcInProgress
本地到过程 无 dblVelocity
如果一个变量在标准模块或窗体模块中被声明为 Public，那么该变量具有全局范
围。如果一个变量在标准模块或窗体模块中被分别声明为 Private，那么该变量有
模块级范围。
注意 一致性是卓有成效地使用这种技术的关键；Visual Basic 中的语法检查器
不会捕捉以 "p." 开头的模块级变量。
常量
常量名的主体是大小写混合的，每个单词的首字母大写。尽管标准 Visual
Basic 常量不包含数据类型和范围信息，但是象 i、s、g 和 m 这样的前缀对于理
解一个常量的值和范围还是很有用的。对于常量名，应遵循与变量相同的规则。例
如：
mintUserListMax '对用户列表的最大限制
'(整数值，本地到模块)
gstrNewLine '新行字符
'(字符串，应用程序全局使用)
变量
声明所有的变量将会节省编程时间，因为键入操作引起的错误减少了（例如，究竟
是 aUserNameTmp，还是 sUserNameTmp，还是 sUserNameTemp）。在“选项”对话
框的“编辑器”标签中，复选“要求变量声明”选项。Option Explicit 语句要求
在 Visual Basic 程序中声明所有的变量。
应该给变量加前缀来指明它们的数据类型。而且前缀可以被扩展，用来指明变量范
围，特别是对大型程序。
变量数据类型
用下列前缀来指明一个变量的数据类型。
数据类型 前缀 例子
Boolean bln blnFound
eanB byt bytRasterData
nByteCollection o col colWidgets
ection o cur curRevenue
on objectCu dtm dtmStart
ectCur dbl dblTolerance
Curre err errOrderNum
rencyDa int intQuantity
yDat lng lngDistance
Object obj objCurrent
ectSin sng sngAverage
Single str strFName
gleStringUser-def udt udtEmployee
User-de vnt vntCheckSum
描述变量和过程名
变量或过程名的主体应该使用大小写混合形式，并且应该足够长以描述它的作用。
而且，函数名应该以一个动词起首，如 InitNameArray 或 CloseDialog。
对于频繁使用的或长的项，推荐使用标准缩略语以使名称的长度合理化。一般来说
，超过 32 个字符的变量名在 VGA 显示器上读起来就困难了。
当使用缩略语时，要确保它们在整个应用程序中的一致性。在一个工程中，如果一
会儿使用 Cnt， 一会儿使用 Count，将导致不必要的混淆。
用户定义的类型
在一项有许多用户定义类型的大工程中，常常有必要给每种类型一个它自己的三个
字符的前缀。如果这些前缀是以 "u" 开始的，那么当用一个用户定义类型来工作
时，快速识别这些类型是很容易的。例如，ucli 可以被用来作为一个用户定义的
客户类型变量的前缀。
1. 5 结构化编码约定
除了命名约定外，结构化编码约定，可以极大地改善代码的可读性，如代码注释和
一致性缩进。
1. 5.01 代码注释约定
所有的过程和函数都应该以描述这段过程的功能的一段简明注释开始（这段例程干
什么）。这种描述不应该包括执行过程细节（它是怎么做的），因为这常常是随时
间而变的，而且这种描述会导致不必要的注释维护工作，甚至更糟—成为错误的注
释。代码本身和必要的嵌入注释将描述实现方法。
当参数的功能不明显且当过程希望参数在一个特定的范围内时，也应描述传递给过
程的参数。被过程改变的函数返回值和全局变量，特别是通过引用参数的那些，也
必须在每个过程的起始处描述它们。
过程头注释块应该包括下列节标题。关于例子，请参阅下节“格式化代码”。
节标题 注释描述
目的 该过程完成什么（而不是怎么完成）。
假设 列出每个外部变量、控件、打开文件或其它不明显元素。
效果 列出每个被影响的外部变量、控件、或文件及其作用（只有当它不明显时）
。
输入 每一个可能不明显的参数。参数分别在单独的行上，并嵌入注释。
返回 函数返回值的说明。
1. 5.02 记住下列几点：
1) 每一个重要变量的声明应该包括一个嵌入注释，来描述该变量的使用。
2) 变量、控件及过程的命名应该足够清楚，使得只有复杂的执行细节才需要嵌入
注释。
3) .Bas 模块包含工程的 Visual Basic 一般常量声明，在其起始处，应该包括
描述应用程序的综述，列举主要数据对象、过程、算法、对话、数据库及系统需求
。有时，一段描述算法的伪码可能会有所帮助。
4) 格式化代码
因为许多程序员仍然使用 VGA 显示器，所以在允许代码格式来反映逻辑结构和嵌
套的同时，应尽可能地省屏幕空间。下面列出几点：
5) 标准的、基于制表位的嵌套块应该被缩进四个空格（缺省情况下）。
6) 过程的功能综述注释应该缩进一个空格。跟在综述注释后面的最高级的语句应
该缩进一个制表位，而每一个嵌套的块再缩进一个制表位。例如：
'*****************************************************
'目的： 在用户列表数组中找出
' 一个指定用户的第一次出现位置。
'输入：
' strUserList()： 被搜索的用户列表。
' strTargetUser： 要搜索的用户名。
' 返回： 在rasUserList 数组中rsTargetUser
' 的第一次出现的索引。
' 如果目标用户没找到，返回-1。
'*****************************************************
Function intFindUser (strUserList() As String, strTargetUser As _
String)As Integer
Dim i As Integer ' 循环计数器。
Dim blnFound As Integer ' 目标寻找标志。
intFindUser = -1
i = 0
While i <= Ubound(strUserList) and Not blnFound
If strUserList(i) = strTargetUser Then
blnFound = True
intFindUser = i
End If
Wend
End Function
7) 给常量分组
变量和定义的常量应该按功能分组，而不是分散到单独区域或特定文件中。Visual
Basic 一般常量应该在单一模块中分组，以将它们与应用程序特定的声明分开。
8) & 和 ＋ 运算符
在连接字符串时总是使用 & 运算符，而当处理数值时常用 ＋ 运算符。当在两个
变体上操作时，用 ＋ 运算符来连接可能会导致问题。例如：
vntVar1 = "10.01"
vntVar2 = 11
vntResult = vntVar1 + vntVar2 'vntResult = 21.01
vntResult = vntVar1 & vntVar2 'vntResult = 10.0111
9) 为 MsgBox、InputBox 及 SQL 查询创建字符串
当产生长字符串时，使用下划线连接字符产生多行代码，这样便于阅读或调试字符
串。当显示一个消息框 (MsgBox) 或输入框 (InputBox)，或产生一个 SQL 字符串
时，这一技术特别有用。例如：
Dim Msg As String
Msg = "This is a paragraph that will be " _
& "in a message box. The text is" _
& " broken into several lines of code" _
& " in the source code, making it easier" _
& " for the programmer to read and debug."
MsgBox Msg
Dim QRY As String
QRY = "SELECT *" _
& " FROM Titles" _
& " WHERE [Year Published] > 1988"
TitlesQry.SQL = QRY
第 二 部份 Java编码规范
2. 1 简 介
Java语言给了程序员充分的空间随意编写自己的代码，但也正是因为如此，一个程
序员自己编写的代码往往不能被别的程序员很好的阅读和理解。Java同样能够让我
们编写出通俗易懂的代码。显然，大多数的开发团队更愿意选择后者，即选择一种
通俗易懂的代码。
本文档旨在提供一个编码的标准，以便所有Java代码在产生的一开始就能够在整个
开发团队中保持一致，从而能够更好的阅读和修改代码。很显然，这样做不仅仅只
是选择一种Java编码方式，更应该是对于一个采用Java标准的开发团队来说唯一的
编写代码的正确途径。
本文档所描述的编码标准有95%是能够在JDK源文件中找到的，其余的5%是由一个开
发团队经过好几个小时的争论最后达成一致的结果。
本文档几乎囊括了所有我们在编码过程中可能产生的疑惑和分歧。那些在我们实际
编码中不可能成为问题的部分，在这里没有描述，但是我们至少会在文档的某些地
方提供一个例子来示范其正确用法。
2. 2 格 式
2. 2.01 缩进
所有的缩进皆为四个空格。对应的括号通常在同一列的位置上。例如：
void foo()
{
while ( bar > 0 )
{
System.out.println();
bar-- ;
}
if ( oatmeal == tasty )
{
System.out.println("Oatmeal is good and good for you");
}
else if ( oatmeal == yak )
{
System.out.println("Oatmeal tastes like sawdust");
}
else
{
System.out.println("tell me pleeze what iz dis 'oatmeal'");
}
switch( suckFactor )
{
case 1:
System.out.println("This sucks");
break;
case 2:
System.out.println("This really sucks");
break;
case 3:
System.out.println("This seriously sucks");
break;
default:
System.out.println("whatever");
break;
}
}
1．所有的缩进是由“Space(空格)键”形成的，而不是“Tab键”。
原因：所有的程序对于“Spaces”都会运行得很好。而大多数程序往往会混淆
Tabs和Spaces，以致于对有些行用Spaces缩进，有些行用Tabs缩进。如果你的Tab
设置是4，而你又把文件共享给了一个Tab设置是8的用户，那么一切都会大乱的。
2．所有的if、while和for语句中的“状态”内容必须用括号括起来，就算只有一
个状态。
原因：一致才能易读。如果代码行有的长出一块，有的短一块，那么整体编辑效果
就很不好，也就失去了易读性。
如下面的比较：
if ( superHero == theTick ) System.out.println("Spoon!"); //不好！
if ( superHero == theTick ) // 好！
{
System.out.println("Spoon!");
}
2. 2.02 间隔
1．所有的标识符都必须被空白字符包围。
原因：有些功能是在你双击某个标识符的时候被选中的。而这些通过双击选中的功
能标识符，有一些是必须严格地被空格符划定界限的，所以周围的任何一个字符都
有可能因为没有设置空格符而一不小心把另一个功能标识符包括在自己的标识符范
围内，从而当用户双击该标识符时产生违背原先意愿的结果。由此可见，使用空白
字符(空格符和换行)围绕标识符还是有必要作为一项规范的。请看下面的比较：
int theTick=5; // 不好! 双击得到的是 "TheTick=5;"
int theTick = 5 ; // 好! 双击得到的是 "TheTick"
if (theTick==5) // 不好! 双击得到的是 "(TheTick==5)"
if ( theTick == 5 ) // 好! 双击得到的是 "TheTick"
这么做唯一可能成为麻烦的是复杂的布尔分析影响了清晰度，例：
if ( ( hero == theTick ) && ( ( sidekick == arthur ) || ( sidekick
== speak ) ) )
不如这样：
boolean isTickSidekick = ( ( sidekick == arthur ) || ( sidekick ==
speak ) );
if ( ( hero == theTick ) && isTickSidekick )
2．然而也有一些例外的情况，见下表：
例 外 情 况 原 由 正 确 示 例 错 误 示 例
方 法 名 习惯写法是在所有方法名之后直接跟上一个左括号 foo( i ) ;
start() ; foo (i) ;start () ;
数 组 习惯写法是在所有数组名之后直接跟上一个左方括号 args[0] ;
tens[ I ] ; args [0] ;tens [i] ;
自加、自减运算符 习惯写法是在所有一元运算符前面或后面直接加上操作数
++count ;i-- ; ++ count ;i -- ;
造型运算符 习惯写法是所有造型都不加空格 (MyClass)v.get( 3 ) ;
(MyClass) v.get( 3 ) ;( MyClass )v.get( 3 ) ;
2. 2.03 空行
应该时不时的在各方法之间加入一些空格行来分割大段的代码；
还应该在方法与方法之间加入一两行的空格行。
2. 2.04 类成员的摆放顺序
class Order
{
// final attributes
// attributes
// constructors
// methods
}
必须保持private方法被放置在使用该方法的其他方法之上，而在构造器（
constructor）之下，即使该构造器有可能调用这些private方法。
2. 2.05 文件格式(File Format)
“package”必须总保持第一个出现；
“import”其次；
再次，任何非javadoc的注释；
然后是javadoc类文件
最后便是类。
注意：一个文件(File)只能有一个类，内部类除外。
示例：
package misc ;
import java.io.* ;
import java.net.* ;
/** this class does cool stuff
@author Joe Programmer
*/
class SpaceMonkey
{
...
}
2. 2.06 行最大长度
不要让一行代码的长度超过120个字符，最好是低于80个字符。如果代码开始向右
延伸得很长，你就应该考虑把它分割成更多的方法。
2. 2.07 括号
使用括号的目的必须是在表达上不但能够标明优先顺序，而且有助于使表达更简单
明了。另外，如果某一段代码有可能产生歧义，也需加括号。
2. 3 标识符
所有的标识符只能用字母（A—Z或a—z）和数字（0—9）。不能有下划线、货币符
号或者其它非ASCII字符。
2. 3.01 类和接口
所有类和接口标识符将都使用混合“格”表示。每个名称中的每个单词首字母必须
大写，同时这个名称的首字母也必须大写；其它的字母均小写，除了缩写词之外（
它们必须全部大写）。
示例：
Customer
SalesOrder
TargetURL
URLTarget
2. 3.02 包
所有包名只能用小写字母。尽量别使包名长度超过8个字符，应该避免使用多个词
作为包名。
示例：
common
core
lang
2. 3.03 其它标识符
其它标识符包括（但不限于）：属性（attributes）、变量（variables）、方法
（methods）和参数（parameters）。它们将沿袭一个默认的命名习惯（同样对
final标识符也适用），就是：
除了名称的首字母之外，名称中其它单词的首字母大写；其余字母小写，但缩写词
的每个字母大写。例如：
customer
salesOrder
targetURL
urlTarget
2. 3.04 get和set方法
用于设置对象状态的方法必须在方法名前面加一个前缀set；用于检索一个布尔类
型对象状态的方法必须在方法名前面加一个前缀is；而用于检索其它类型对象状态
的方法则必须在方法名前面加上get。
示例：
setEnabled()
getName()
isEnabled()
2. 4 注 释
大部分注释尽量用“//”；对于所有的javadoc的注释则用“/** */”；而临时对
代码块进行的注释尽量用“/* */”。
2. 4.01 JavaDoc
1．JavaDoc注释将用于说明那些被其它类调用的类、属性和方法。这些注释必须出
现在所要说明的各项之前。
2．JavaDoc注释一般不会用于说明一些显而易见的方法，例如：
public static void main( String[ ] args ) 或public int getX( ) ；
3．JavaDoc注释也不用于说明一些显而易见的参数，如：
public void setX( int newX ) ；
4．诸如servlet和EJB等那些没有被其它类调用的类，也不必加JavaDoc注释。
把源码上交给整个团队之前，必须先经过JavaDoc处理，并全面检查处理结果，以
确定说明文字确实可读而且清楚明白。
如果JavaDoc注释能够在一行内写下，则格式应该象下面这样：
/** Used to mark spots */
int x ;
如果JavaDoc注释内容在一行内容纳不下，则其格式应该象下面这样：
/** Set how much to grow when growth is needed. <p>
Smaller values will usually save memory, but frequent
reallocation may take a lot of time. <p>
@param HowMuch The number of extra ints to allocate when
memory reallocation is required. Values must be greater than
zero. <p>
*/
public void setExtra( int HowMuch )
{
注意：HTML标签<p>和<pre>的作用。<p>迫使一段代码进行分行，而<pre>…
</pre>则让块文字以特定的字体表现出来并且保留所有的空格字符。
JavaDoc还允许使用其它的HTML标签，但是禁止使用header标签（如<h1>, <h2>等
）你可以用<b>..</b>加黑文字，也可以用<I>..</I>使文字变为斜体。
注意：JavaDoc把每个JavaDoc注释的第一行划分出来以用于放置“内容表”。如何
标识出这部分内容的结束边界线呢？JavaDoc定义这个标志为“一个句号后跟一个
空格”。其它如“一个问号后跟一个空格”或“一个句号后跟一个<p>标签”都不
是结束标志。如果在句号和<p>之间加一个空格，那么就有结束标志产生了。
(a) 类
类的JavaDoc说明文件必须包括以下内容：
（1）简要的提纲
（2）详细的描述
（3）使用该类的示例代码段
（4）用@author标签列出作者
注意：由于JavaDoc中一个“功能（feature）”限制，所有示例代码的每行前面必
须加入一个星号，以便保存每行的缩进。例如：
/** A vector class optimized for working with ints. <p>
Like the Vector object, except rather than tracking a dynamic
array of pointers to different objects, this is simply a
dynamic array of ints. The advantage is speed and memory
savings.<p>
Example:
<pre>
*
* // report longest lines
* TextFileIn f = new TextFileIn("blather.txt");
* IntVector v = new IntVector();
* int longestLine = 0 ;
* boolean done = false ;
* while ( ! done )
* {
* String s = f.readLine();
* if ( s == null )
* {
* done = true ;
* }
* else
* {
* int sLength = s.length() ;
* if ( sLength > longestLine )
* {
* longestLine = sLength ;
* }
* v.append( sLength );
* }
* }
* f.close();
* System.out.println("The longest lines are on line numbers:
");
* for ( int i = 0 ; i < v.length() ; i++ )
* {
* if ( v.get( i ) == longestLine )
* {
* System.out.println( i );
* }
* }
</pre>
@author Adam Baum
@author Justin Case
*/
public class IntVector
{
(b) 方法
方法的JavaDoc说明文档必须包含以下内容：
（1）简要的提纲；
（2）详细的描述（如果有必要在简要提纲内补充说明某些内容的话）；
（3）用JavaDoc的@param标签列出所有参数（如果有参数的话）；
（4）用JavaDoc的@return标签返回出方法的值列表（如果需要返回值的话）；
（5）用JavaDoc的@exception标签列出所有异常（exception）(如果有异常抛出的
话)
示例：
/** Get a copy of one int. <p>
Retrieve an int relative to the index provided.<p>
@param Index Which int (0 is the first int).<p>
@return The retrieved int or zero if Index is outside of 0..
length.<p>
*/
public int get( int Index )
{
2. 4.02 代码的自我说明
“傻子写计算机识别的程序；程序员写人识别的程序。”
——Martin Fowler, Refactoring：《提高代码的设计水平》
除了要尽力用文件说明程序的复杂算法，我们还必须尽量通过多用一些标识符来使
程序的算法易读。这样有助于减少将来需要修改程序而不需修改说明文档而带来的
麻烦。
例 如：
原始代码：
/** determine if the given year is a leap year. <p>
The Gregorian calendar principal states that a leap year
occurs
every fourth year, except every 100 years, except every 400
years. <p>
If the year is evenly divisible by 400 or is evenly divisible
by
4 and not by 100, then it is a leap year. <p>
@param year The year to be tested. Make sure this is a four
digit year! <p>
@return true if "year" is a leap year. <p>
*/
boolean isLeapYear( int year )
{
return ( ( ( y % 400 ) == 0 ) || ( ( ( y % 4 ) == 0 ) && ( ( y %
100 ) != 0 ) ) );
}
修改后的代码：
/** determine if the given year is a leap year. <p>
The Gregorian calendar principal states that a leap year
occurs
every fourth year, except every 100 years, except every 400
years. <p>
@param year The year to be tested. Make sure this is a four
digit year!<p>
@return true if "year" is a leap year. <p>
*/
boolean isLeapYear( int year )
{
boolean y4 = ( ( year % 4 ) == 0 ) ;
boolean y100 = ( ( year % 100 ) == 0 ) ;
boolean y400 = ( ( year % 400 ) == 0 ) ;
return ( y400 || ( y4 && ! y100 ) );
}
或者可以这样：
/** determine if the given year is a leap year. <p>
The Gregorian calendar principal states that a leap year
occurs
every fourth year, except every 100 years, except every 400
years. <p>
@param year The year to be tested. Make sure this is a four
digit year! <p>
@return true if "year" is a leap year. <p>
*/
boolean isLeapYear( int year )
{
boolean returnVal = false ;
if ( ( year % 400 ) == 0 )
{
// this is definitely a leap year
returnVal = true ;
}
else if ( ( year % 4 ) == 0 )
{
// this is probably a leap year
if ( ( year % 100 ) == 0 )
{
// this is definitely not a leap year
// do nothing
}
else
{
// this is definitely a leap year
returnVal = true ;
}
}
return returnVal ;
}
2. 5 编 码
2. 5.01 决不要使用的结构
(a) 决不要使用do…while结构
不要用do…while循环
原因：一般来说，程序员看程序总是在每个方法代码的开头查找该方法的起始处，
然后顺次查找它的执行体。当遇到一个循环时，程序员的第一反应就是想知道它的
循环终结点在哪里。如果你将循环结束逻辑语句放在你的代码最后，那么你的代码
将极难阅读。更糟的是，有许多欠经验的程序员对do…while结构根本不熟，他们
会让你重写程序的。
所以，最好不要这么写代码：
boolean done = false ;
do
{
...
} while( ! done )
而应该是：
boolean done = false ;
while ( ! done )
{
...
}
(b) 决不要在一个方法的中间使用“return”
“return”只能出现在一个方法的末尾。
原因：在方法的中间使用“return”会给今后将方法拆分成几个更小的方法带来困
难；而且它会迫使开发者不得不为该方法考虑多于一个的出口点。
(c) 决不要用“continue”
决不要用“continue”。
原因：continue会给将来把一个结构拆分成几个更小的结构或方法带来许多困难；
而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。
(d) 决不要使用“break”，除非是转换状态（switch statement）控制
“break”只能用于转换状态的控制。
原因：在转换状态控制之外的情况下使用break，会给将来把一个结构拆分成几个
更小的结构或方法带来许多困难；而且她也会迫使开发者不得不为该结构考虑多于
一个的结束点。
2. 5.02 不要混合使用递增运算符和递减运算符
原因：在方法调用或是数学运算中混合使用递增运算符（或递减运算符）会造成欠
经验的程序员阅读的困难，他们也许会让你重写代码的。
所以，最好在递增运算符（或递减运算符）之间加上额外的行。
例如：
foo( x++ ); // 不好!
foo( x ) ; // 好!
x++ ;
y += 100 * x++ ; // 不好!
y += 100 * x ; // 好!
x++ ;
2. 5.03 初始化
最好总是在每个变量出现的时候就马上进行初始化。
最好只在需要的时候再声明（declare）一个变量，不然的话会影响代码的执行效
果。
示例：
int totalWide ;
int firstWide = 20 ;
int secondWide = 12 ;
firstWide = doFoo( firstWide , secondWide );
doBar( firstWide , secondWide );
totalWide = firstWide + secondWide ; // wrong!
int firstWide = 20 ;
int secondWide = 12 ;
firstWide = doFoo( firstWide , secondWide );
doBar( firstWide , secondWide );
int totalWide = firstWide + secondWide ; // right!
int secondWide = 12 ;
int firstWide = doFoo( 20 , secondWide );
doBar( firstWide , secondWide );
int totalWide = firstWide + secondWide ; // even better!
2. 5.04 范围（scope）
除内部类之外的所有类的所有属性必须总是private。
第 三 部份 Java编程规则
摘自《Thinking in JAVA》
(1) 类名首字母应该大写。字段、方法以及对象（句柄）的首字母应小写。对
于所有标识符，其中包含的所有单词都应紧靠在一起，而且大写中间单词的首字母
。例如：
ThisIsAClassName
thisIsMethodOrFieldName
若在定义中出现了常数初始化字符，则大写static final基本类型标识符中的所有
字母。这样便可标志出它们属于编译期的常数。
Java包（Package）属于一种特殊情况：它们全都是小写字母，即便中间的单词亦
是如此。对于域名扩展名称，如com，org，net或者edu等，全部都应小写（这也是
Java 1.1和Java 1.2的区别之一）。
(2) 为了常规用途而创建一个类时，请采取“经典形式”，并包含对下述元素
的定义：
equals()
hashCode()
toString()
clone()（implement Cloneable）
implement Serializable
(3) 对于自己创建的每一个类，都考虑置入一个main()，其中包含了用于测试
那个类的代码。为使用一个项目中的类，我们没必要删除测试代码。若进行了任何
形式的改动，可方便地返回测试。这些代码也可作为如何使用类的一个示例使用。
(4) 应将方法设计成简要的、功能性单元，用它描述和实现一个不连续的类接
口部分。理想情况下，方法应简明扼要。若长度很大，可考虑通过某种方式将其分
割成较短的几个方法。这样做也便于类内代码的重复使用（有些时候，方法必须非
常大，但它们仍应只做同样的一件事情）。
(5) 设计一个类时，请设身处地为客户程序员考虑一下（类的使用方法应该是
非常明确的）。然后，再设身处地为管理代码的人考虑一下（预计有可能进行哪些
形式的修改，想想用什么方法可把它们变得更简单）。
(6) 使类尽可能短小精悍，而且只解决一个特定的问题。下面是对类设计的一
些建议：
■一个复杂的开关语句：考虑采用“多形”机制
■数量众多的方法涉及到类型差别极大的操作：考虑用几个类来分别实现
■许多成员变量在特征上有很大的差别：考虑使用几个类
(7) 让一切东西都尽可能地“私有”——private。可使库的某一部分“公共化
”（一个方法、类或者一个字段等等），就永远不能把它拿出。若强行拿出，就可
能破坏其他人现有的代码，使他们不得不重新编写和设计。若只公布自己必须公布
的，就可放心大胆地改变其他任何东西。在多线程环境中，隐私是特别重要的一个
因素——只有private字段才能在非同步使用的情况下受到保护。
(8) 谨惕“巨大对象综合症”。对一些习惯于顺序编程思维、且初涉OOP领域的
新手，往往喜欢先写一个顺序执行的程序，再把它嵌入一个或两个巨大的对象里。
根据编程原理，对象表达的应该是应用程序的概念，而非应用程序本身。
(9) 若不得已进行一些不太雅观的编程，至少应该把那些代码置于一个类的内
部。
(10) 任何时候只要发现类与类之间结合得非常紧密，就需要考虑是否采用内部
类，从而改善编码及维护工作（参见第14章14.1.2小节的“用内部类改进代码”）
。
(11) 尽可能细致地加上注释，并用javadoc注释文档语法生成自己的程序文档
。
(12) 避免使用“魔术数字”，这些数字很难与代码很好地配合。如以后需要修
改它，无疑会成为一场噩梦，因为根本不知道“100”到底是指“数组大小”还是
“其他全然不同的东西”。所以，我们应创建一个常数，并为其使用具有说服力的
描述性名称，并在整个程序中都采用常数标识符。这样可使程序更易理解以及更易
维护。
(13) 涉及构建器和异常的时候，通常希望重新丢弃在构建器中捕获的任何异常
——如果它造成了那个对象的创建失败。这样一来，调用者就不会以为那个对象已
正确地创建，从而盲目地继续。
(14) 当客户程序员用完对象以后，若你的类要求进行任何清除工作，可考虑将
清除代码置于一个良好定义的方法里，采用类似于cleanup()这样的名字，明确表
明自己的用途。除此以外，可在类内放置一个boolean（布尔）标记，指出对象是
否已被清除。在类的finalize()方法里，请确定对象已被清除，并已丢弃了从
RuntimeException继承的一个类（如果还没有的话），从而指出一个编程错误。在
采取象这样的方案之前，请确定finalize()能够在自己的系统中工作（可能需要调
用System.runFinalizersOnExit(true)，从而确保这一行为）。
(15) 在一个特定的作用域内，若一个对象必须清除（非由垃圾收集机制处理）
，请采用下述方法：初始化对象；若成功，则立即进入一个含有finally从句的
try块，开始清除工作。
(16) 若在初始化过程中需要覆盖（取消）finalize()，请记住调用super.
finalize()（若Object属于我们的直接超类，则无此必要）。在对finalize()进行
覆盖的过程中，对super.finalize()的调用应属于最后一个行动，而不应是第一个
行动，这样可确保在需要基础类组件的时候它们依然有效。
(17) 创建大小固定的对象集合时，请将它们传输至一个数组（若准备从一个方
法里返回这个集合，更应如此操作）。这样一来，我们就可享受到数组在编译期进
行类型检查的好处。此外，为使用它们，数组的接收者也许并不需要将对象“造型
”到数组里。
(18) 尽量使用interfaces，不要使用abstract类。若已知某样东西准备成为一
个基础类，那么第一个选择应是将其变成一个interface（接口）。只有在不得不
使用方法定义或者成员变量的时候，才需要将其变成一个abstract（抽象）类。接
口主要描述了客户希望做什么事情，而一个类则致力于（或允许）具体的实施细节
。
(19) 在构建器内部，只进行那些将对象设为正确状态所需的工作。尽可能地避
免调用其他方法，因为那些方法可能被其他人覆盖或取消，从而在构建过程中产生
不可预知的结果（参见第7章的详细说明）。
(20) 对象不应只是简单地容纳一些数据；它们的行为也应得到良好的定义。
(21) 在现成类的基础上创建新类时，请首先选择“新建”或“创作”。只有自
己的设计要求必须继承时，才应考虑这方面的问题。若在本来允许新建的场合使用
了继承，则整个设计会变得没有必要地复杂。
(22) 用继承及方法覆盖来表示行为间的差异，而用字段表示状态间的区别。一
个非常极端的例子是通过对不同类的继承来表示颜色，这是绝对应该避免的：应直
接使用一个“颜色”字段。
(23) 为避免编程时遇到麻烦，请保证在自己类路径指到的任何地方，每个名字
都仅对应一个类。否则，编译器可能先找到同名的另一个类，并报告出错消息。若
怀疑自己碰到了类路径问题，请试试在类路径的每一个起点，搜索一下同名的.
class文件。
(24) 在Java 1.1 AWT中使用事件“适配器”时，特别容易碰到一个陷阱。若覆
盖了某个适配器方法，同时拼写方法没有特别讲究，最后的结果就是新添加一个方
法，而不是覆盖现成方法。然而，由于这样做是完全合法的，所以不会从编译器或
运行期系统获得任何出错提示——只不过代码的工作就变得不正常了。
(25) 用合理的设计方案消除“伪功能”。也就是说，假若只需要创建类的一个
对象，就不要提前限制自己使用应用程序，并加上一条“只生成其中一个”注释。
请考虑将其封装成一个“独生子”的形式。若在主程序里有大量散乱的代码，用于
创建自己的对象，请考虑采纳一种创造性的方案，将些代码封装起来。
(26) 警惕“分析瘫痪”。请记住，无论如何都要提前了解整个项目的状况，再
去考察其中的细节。由于把握了全局，可快速认识自己未知的一些因素，防止在考
察细节的时候陷入“死逻辑”中。
(27) 警惕“过早优化”。首先让它运行起来，再考虑变得更快——但只有在自
己必须这样做、而且经证实在某部分代码中的确存在一个性能瓶颈的时候，才应进
行优化。除非用专门的工具分析瓶颈，否则很有可能是在浪费自己的时间。性能提
升的隐含代价是自己的代码变得难于理解，而且难于维护。
(28) 请记住，阅读代码的时间比写代码的时间多得多。思路清晰的设计可获得
易于理解的程序，但注释、细致的解释以及一些示例往往具有不可估量的价值。无
论对你自己，还是对后来的人，它们都是相当重要的。如对此仍有怀疑，那么请试
想自己试图从联机Java文档里找出有用信息时碰到的挫折，这样或许能将你说服。
(29) 如认为自己已进行了良好的分析、设计或者实施，那么请稍微更换一下思
维角度。试试邀请一些外来人士——并不一定是专家，但可以是来自本公司其他部
门的人。请他们用完全新鲜的眼光考察你的工作，看看是否能找出你一度熟视无睹
的问题。采取这种方式，往往能在最适合修改的阶段找出一些关键性的问题，避免
产品发行后再解决问题而造成的金钱及精力方面的损失。
(30) 良好的设计能带来最大的回报。简言之，对于一个特定的问题，通常会花
较长的时间才能找到一种最恰当的解决方案。但一旦找到了正确的方法，以后的工
作就轻松多了，再也不用经历数小时、数天或者数月的痛苦挣扎。我们的努力工作
会带来最大的回报（甚至无可估量）。而且由于自己倾注了大量心血，最终获得一
个出色的设计方案，成功的快感也是令人心动的。坚持抵制草草完工的诱惑——那
样做往往得不偿失。
(31) 可在Web上找到大量的编程参考资源，甚至包括大量新闻组、讨论组、邮
寄列表等。下面这个地方提供了大量有益的链接：
正文完
--
今天没什么好玩的事编程资料：1.201/study/my document/，也许有你要的东西 ★
★ ┬┬ /
★ ▕▂▂●--
★ ★ ██
▂██▂
███████████████████～~～~* OICQ:86395
※ 来源:·荔园晨风BBS站 bbs.szu.edu.cn·[FROM: 192.168.1.201]
[回到开始]
[上一篇][下一篇]
荔园在线首页 友情链接：深圳大学 深大招生 荔园晨风BBS S-Term软件 网络书店