1、API Coding 编程规范(1)()2001/4/5你是个天才, 熬夜写了 5000 行的代码, 实现了前所未有的功能, 不过到了第二天你就无法順利解读那份代码. 又过了一个月, 有人向你问起有关这段代,码的问题, 你赌咒发誓那不是你写的, 是这样吗?你一定看过 Microsoft, Inprise, Sun 公司的源代码, 你会怀疑那些是否出自一台會 Coding 的及器吗?.如果是, 请遵循大汉网络 API Coding 规范.概述: 对于一个软件工厂,并不需要一个我行我素的机灵蛋, 您所使用的技巧应遵循一定的约束, 否则您的 Source 不能被他人解读. 造成资源维护困难, 将不能
2、成为公司的有效资源 . 要相信 bug 一定会有,只是暂时未发现. 因为一切都在进步,不断推陈出新. 没有最好只有更好. 一. Class/Interface/Method 命名约定Class/Interface必须以大写字母开头, 如:Class SaveThread extends ThreadInterface DSIRemoveAll Method(方法, 函数)必须以小写字母开头,Method 名应使用大小写混合形式, 并且应足够长以描述它的作用. 而且, Method 名应以一个动词起手，如 initNameArray() closeDialog()还应注意 Method 不要太长
3、 ,结构简单的一般不超过 200 行,结构复杂的一般不超过 100 行.您可回想一些,您 1000行代码的 Method, 真的不可拆为 10 个 Method 的吗?二. 常量变量命名约定常量必须全部大写, 如:public static final int MAXLINES;建议多定义或使用常量, 而不是数字(或字母)例如:if(argv23=0.0f)else这是很危险的做法, 正确的做法是使用常量, 如23表示为金额 :final static int SUM=23;if(argvSUM=0.0f)else很明显, 好处有二: 1.Source 容易阅读; 2.当数组序列刪除或增加某个
4、元素时, 只要修改常量定义值.就可以了还有一个写法是创建 Class 将 argv封装起来.Class ReportOptionpublic ReportOption(String argv)public boolean isPrintSum()变量1.以小写字母开头 , 如:int ni;2.加数据类型前缀, 如:String strName;建议以下常用数据类型之前缀:类型 前缀 例子基本数据类. boolean / Boolean . bl . blOK. char / Char . ch . chRead. byte / Byte . b . bWrite. int / Integer
5、 . n . nLength. short / Short . s . sCount. long / Long . l . lTotal. float / Float . f . fSum. double / Double . d . dSum常用数据类. String . str . strNameArray. StringHolder . strhd . strhdNameArray. Vector . v . vData. HashTable . ht . htRecord. HashMap . hm . hmRecord. Calender . cal , cal与 SQL 相关的类.
6、 Connection . conn . connNow. Statement . stmt . stmtQueryAll. PreparedStatement . pstmt . pstmtQueryCustomJAVA 控制类. Jlabel . _lab . _labText. DateLabel . _dlab . _dlabText. NumberLabel . _nlab . _nlabText. Jbutton . _btn . _btnOK. JtextField . _tf . _tfName. JtextFieldPopup . _tfpop . _tfpopName. J
7、textArea . _ta . _taAddress. JtextAreaPopup . _tapop . _tapopAddress. JcomboBox . _comb . _combType. JradioButton . _rbtn . _rbtnSelect. JcheckBox . _cbox . _cboxOption. Pin . _spin . _spinDate. NumberEdit . _ne . _neSum. FreeNumberEdit . _fne . _fneSum. ComboNumberEdit . _cne . _cneSum. ComboDateEd
8、it . _cde . _cdeBillDate. LiveTable . _table . _tableProduct. JCDataSource . _ds . _dsProduct. . . 3.加变量范围, 全局加 m_, 如 :Class TestThread extends ThreadString m_strName;Public TestThread(String strName)m_strName=strName;4.请使用标准的英文 Name.三. 结构化编程规约(请按以下执行 )(参考文献)除了命名約定外, 結构化編碼約定, 可以極大地改善代碼的可讀性, 如代碼註釋和一致
9、性縮進. 1. Class/Interface 文件頭註釋約定每一 Source 須加標準 Head Script, 另外還需要”功能描述”說明此 Source 的功能./*/ Project: MERP/ Copyright 2000-2005 Dahan Net, All Right Reserved/ $Workfile: PS_DE0001.java $/ $Header: 1.12 Jun 20 2001 09:06:54 chemain $/*/*功能描述:*/2. Method 註釋約定所有的 Method 都應該以描述这段代碼的功能的一段簡明註釋始(这段代碼干什么). 这种描述
10、不應該包括执行过程( 它是怎么做的)，因為这常常是随时間而變的，而且这种描述会導致不必要的註釋工作，甚至更糟成為錯誤的註釋. 代碼本身和必要的嵌入註釋將描述实現方法 .当参数的功能不明顯, 且当 Method 希望参数在一个特定的范圍内时，也應描述傳递給 Method 的参数. 被 Method 改變的函数返回值 , 參數及全局變量, 在每个 Method 的起始处描述它.过程头註釋块應該包括下列標題. 關于例子, 請参閱下節“格式化代碼”.標題 註釋描述目的 Method 完成甚麼（而不是怎麼完成）輸入參數 每一个輸入参数分别在单独的行上，并嵌入註释。返回值 函数返回值的說明。包括對全局量的
11、影響.在 Method 實體中記住下列几点:A.每一个重要變量的声明應該包括一个嵌入註釋，来描述變量的使用.B.變量、控件及 Method 的命名應該足够清楚, 使得只有复雜的执行細節才需要嵌入註釋 .C.列舉主要数据对象、Method、算法、数据庫及系統需求. 一段描述算法的偽代碼能会有所帮助。3. 格式化代碼因為顯示器空間有限，所以在允許代碼格式来反映逻輯构和嵌套的同时，尽可能地省屏幕空間。下面列出几点： 標準准的、基于制表位的嵌套块應該被縮進 4 个空格（請調整 Source Editor 的制表位）。Method 的功能綜述應該縮進一个空格。跟在綜述註釋后面的最高級的語句縮進一个制表位
12、，而每一个嵌套的块再縮進一个制表位。例如： /*目的: 找出一個 String 在一個 String中位置 index輸入: strArray : String 數組 strFind : 需要找的 String返回: =0 : 找到, 返回 strDind 在 strArray 中的 index -1 : 沒找到*/public int compString(String strArray, String strFind)/空值輸入, 返回-1if(strArray=null|strFind=null)return -1;/循環for(int ni=0;nistrArray.length();
13、ni+)if(strArrayni.equals(strFind) /是否匹配return ni; /返回 index/沒找到, 返回-1return -1;另外:和 必須上下對齊 ,條件判斷後的執行語句必須另起新行, 如void function(.)if(condition) / braces on the next linedo something.esledo something./ the following style is bad for debugging/ if(condition) do something/ / switchswitch(condition)case CA
14、SE1:do somthing.break;case CASE2:do something.break;default:do something.break;有關 SQL Script 的格式, 這裡必須做特別說明A. SQL 語句前必須註釋說明功能, 各段必須另起新行(新行+”後必留一空格), 每行後加註釋, 如/得到現有客戶的聯絡電話-1,聯絡電話-2String strQuery=“ select tba06c, tba07c” /tba06c:聯絡電話-1,tba07c:聯絡電話-2+“ from tbm01“ /客戶基本資料主档+“ where tba010c=B and tba01
15、1c=“+strCusomerNO;/tba010c:類別碼(B/P),tba011c:客戶編號B. 當遇到欄位較多, 不容易對應時應每個欄位一行, 如:你能很快看懂下面一段程式並 Debug 嗎?String strQuery=“ insert into dim04 (compno,no,billtype,nokey,nodate,did03c,did05c,did06c,did09c,did10c,did11c,did121c,did122f,did124f,did13c,did141f,did142f,did143f,did16f,did17f,did18f,did19f,did20f,
16、did21f,userid,did222c,did231c,did232c,did24c,did251c,did252c,did26c,did27c,did28c,group_bill,group_no,time) “+“ values(1,“+StringUtil.filtNull(T4)+“,billtype,“ +“ nokey,“+StringUtil.filtNull(T2)+“,“+StringUtil.filtNull(T9)+“,“ +“ convert(varchar(10),“+StringUtil.filtNull(T3)+“),“ +“ convert(varchar(
17、20),“+StringUtil.filtNull(did09c)+“),“ +“ convert(varchar(20),“+StringUtil.filtNull(did10c)+“),“+“ convert(varchar(20),“+StringUtil.filtNull(did11c)+“),NT$,1,“+did124f+“,“+“ 0,100,100,100,did20f-did17f“ +“ ,did17f,0,isnull(did19f,0),did20f,0,admin,“+curdate+“,“ +“ ,0,“ +“ convert(varchar(4),“+String
18、Util.filtNull(T5)+“),1,0,“ +“ DM0005“+“ “+StringUtil.filtNull(T9)+“,“+“ ) “;但如果寫成這樣, 就很清楚, 有的計算可以在 JAVA 中完成 , 可以更快, /新增一筆進貨單String strQuery=“insert into dim04(“+“ compno, “ /0 /* 公司別 TYPE_CMPID */+“ no, “ /1 /* 單號 TYPE_BILLNO */+“ billtype, “ /2 /* 單別 TYPE_BILLTYP */+“ nokey, “ /3 /* 單號 key TYPE_BIL
19、LNO_key*/+“ nodate, “ /4 /* 銷貨/銷退/進貨/進退日期 TYPE_DATE */+“ did03c, “ /5 /* 負責業務 varchar(10) */+“ did05c, “ /6 /* 客戶編號 varchar(10) */+“ did06c, “ /7 /* 對方單號 TYPE_BILLNO */+“ did09c, “ /8 /* 電話 varchar(20) */+“ did10c, “ /9 /* 傳真 varchar(20) */+“ did11c, “ /10 /* 聯絡人 varchar(20) */+“ did121c, “ /11 /* 幣
20、別-1 varchar(5) */+“ did122f, “ /12 /* 匯率-1 , NT$ float */+“ did124f, “ /13 /* 匯率-2 float */+“ did13c, “ /14 /* 稅別 0-內含 1-外加 2-免稅 3-零稅率 TYPE_ENUM */+“ did141f, “ /15 /* 折數-1 float */+“ did142f, “ /16 /* 折數-2 float */+“ did143f, “ /17 /* 折數-3 float */+“ did16f, “ /18 /* 貨品金額 float */+“ did17f, “ /19 /
21、* 稅額 float */+“ did18f, “ /20 /* 運費 float */+“ did19f, “ /21 /* 加扣款 float */+“ did20f, “ /22 /* 總金額 float */+“ did21f, “ /23 /* 標準成本總金額 float */+“ userid, “ /24 /* 登錄人 varchar(10) */+“ did222c, “ /25 /* 登錄日期 TYPE_DATE */+“ did231c, “ /26 /* 覆核人 varchar(10) */+“ did232c, “ /27 /* 覆核日期 TYPE_DATE */+“
22、did24c, “ /28 /* 開立發票否: 0.開立 1.不開 2.後補 TYPE_ENUM */+“ did251c, “ /29 /* 帳款單號 TYPE_BILLNO_key*/+“ did252c, “ /30 /* 傳票編號 傳票類別 =3 TYPE_BILLNO */+“ did26c, “ /31 /* 倉庫編號 varchar(4) */+“ did27c, “ /32 /* 是否內部單據 varchar(1) */+“ did28c, “ /33 /* 是否外購 varchar(1) */+“ group_bill, “ /34 /* 單據表組/作業組 TYPE_BILL
23、_GROUP*/+“ group_no, “ /35 /* 單據表/作業 TYPE_GROUP */+“ time) “ /36 /* Update time varchar(14) */+“ values(“+“ 1,“ /0 /* 公司別 TYPE_CMPID */ +“ “+strBillNO+“,“ /1 /* 單號 TYPE_BILLNO */+“ “+strBilltype+“,“ /2 /* 單別 TYPE_BILLTYP */+“ “+strNOKey+“,“ /3 /* 單號 key TYPE_BILLNO_key*/+“ “+strDate+“,“ /4 /* 銷貨/銷退/進貨/進退日期 TYPE_DATE */+“ “+strOperation+“,“ /5 /* 負責業務 varchar(10) */+“ “+strCustomerNO+“,“/6 /* 客戶編號 varchar(10) */+“ ,“ /7 /* 對方單號 TYPE_BILLNO */
