PB命名規(guī)范.doc

第1章 - 應(yīng)用系統(tǒng)源程序基本規(guī)范1. 程序命名規(guī)則命名方法之所以要標(biāo)準(zhǔn)化，主要出于以下幾個(gè)目的。1) 即使只從名字，也可以判斷出起什麼作用？ 是何種類型？ 提高了可讀性及可維護(hù)性；2) 避免編譯及鏈接時(shí)的沖突/不一致，而這種沖突/不一致在把一些模塊移到別的一些操作系統(tǒng)中時(shí)有可能發(fā)生；3) 閱讀源程序以及進(jìn)行調(diào)試時(shí)，某個(gè)符號(hào)屬于哪一個(gè)模塊，能很快的明白；4) 和用途直接有關(guān)的固有名詞的使用， 能夠防止由于疏忽而錯(cuò)誤地使用于別的用途。對(duì)于變量來(lái)說(shuō)，一個(gè)用途一個(gè)變量是一個(gè)重要的原則；5) 可維護(hù)性。命名的方法是隨著軟件系統(tǒng)開(kāi)發(fā)使用的編程語(yǔ)言和編程工具的不同而變化的。 例如：編程語(yǔ)言的不同決定了可使用的字符，X-Windows編程時(shí)使用X-Windows形式的命名原則因此，詳細(xì)的規(guī)定必須根據(jù)項(xiàng)目Project的不同情況而定?！伴_(kāi)始編程之前，必須設(shè)定編程詳細(xì)準(zhǔn)則”是一個(gè)必須遵守的原則。以下，將闡述我們?cè)谠O(shè)定詳細(xì)準(zhǔn)則時(shí)，一些必須考慮到的基本原則，并提供一些范例。標(biāo)識(shí)符是程序中用來(lái)代表變量、標(biāo)號(hào)、函數(shù)、窗口、菜單、控件和對(duì)象等名稱的符號(hào)在源程序中使用的標(biāo)識(shí)符（變量，函數(shù)，文件），應(yīng)該滿足下列基本條件：1、 必須以字母或下劃線開(kāi)頭； 2、 其它可以是字母、數(shù)據(jù)及些特殊符號(hào)；3、 最長(zhǎng)為40個(gè)字符，中間不能有空格；4、 保留字不能作為標(biāo)識(shí)符；5、 根據(jù)其名稱，可以容易地推斷它的用途；6、 根據(jù)其名稱，可以容易地推斷變量的作用域和類型 1) 變量的命名及定義對(duì)于PB來(lái)說(shuō)，它有五個(gè)系統(tǒng)預(yù)定義的全局的變量：SQLCA、SQLDA、SQLSA、Message、Error，這五個(gè)變量名在程序中不要顯式定義，其它變量名的定義遵循如下規(guī)則：權(quán)限（A） + 類型縮寫(xiě)（B） + _ + 拼音縮寫(xiě)、英文（C）說(shuō)明：（1）、定義的變量一律小寫(xiě)； （2）、權(quán)限（A）列表：權(quán)限縮寫(xiě)全局變量g共享變量s實(shí)例變量i局部變量l （3）、類型縮寫(xiě)（B）數(shù)據(jù)類型縮寫(xiě)B(tài)olbBbBooleanBChar 或 CharacterCDateDDateTimeDtDec 或 DecimalDcDoubleDbInteger 或 IntILongLRealRStringSTimeTmUnsignedInteger 或 Unsignedint 或 UintUiUnsignedLong 或 UlongUl （4）、拼音碼縮寫(xiě)（C）:能表達(dá)此變量用途的中文拼音縮寫(xiě) 例如：統(tǒng)計(jì)數(shù)據(jù)窗口返回的總行數(shù)則可定義變量 Int li_zhs （5）、例子：Int li_zhs Long ll_hd 變量的定義遵循如下語(yǔ)法：數(shù)據(jù)類型精度 變量名數(shù)值 =初值，變量名數(shù)值 =初值.說(shuō)明：（1）、數(shù)據(jù)類型采用首字母大寫(xiě)，其它小寫(xiě)； （2）、變量的命名以上面的規(guī)定為準(zhǔn)。 變量的定義注意點(diǎn)： （1）、一個(gè)變量一個(gè)用途 一個(gè)變量，只使用在一個(gè)用途上，決不用于復(fù)數(shù)個(gè)用途上。無(wú)論是在開(kāi)始編程階段，還是在維護(hù)的階段做功能追加及變更時(shí)，都應(yīng)該遵守該原則。但是局部的循環(huán)記數(shù)變量屬于例外。 （2）、一個(gè)文字的變量名 一個(gè)文字的變量名如 i,j等 盡可能不要使用。 尤其不能在全局變量中使用。如果使用了，當(dāng)某個(gè)功能發(fā)生變更時(shí)，將導(dǎo)致和該變量有關(guān)部分要變更。要檢索出使用了該變量的部分很困難。全局變量等重要的變量至少使用2文字以上的字符，這樣使用編輯器可以無(wú)遺漏地方便地檢索出。 （3）、給變量名一個(gè)正確的含義 使用正確的名字給變量命名，即變量名和用途相符合， 以免維護(hù)人員產(chǎn)生錯(cuò)誤的理解。（能用英文單詞修飾盡量用英文單詞，否則用拼音碼縮寫(xiě)）。 （4）、變量全部小寫(xiě)2) PB對(duì)象的命名部分PB對(duì)象前綴：結(jié)構(gòu) str用戶對(duì)象 u菜單 m生成新的對(duì)象后必須在庫(kù)中對(duì)象的屬性中加入注解。（1）、函數(shù)： 應(yīng)用系統(tǒng)級(jí)：f_拼音縮寫(xiě)、英文窗口級(jí)： wf_拼音縮寫(xiě)、英文用戶對(duì)象級(jí)：uf_拼音縮寫(xiě)、英文菜單級(jí)： mf_拼音縮寫(xiě)、英文 （2）、結(jié)構(gòu)：應(yīng)用系統(tǒng)級(jí)：str_拼音縮寫(xiě)、英文窗口級(jí)： wstr_拼音縮寫(xiě)、英文用戶對(duì)象級(jí)：ustr_拼音縮寫(xiě)、英文菜單級(jí)： mstr_拼音縮寫(xiě)、英文（3）、窗口： 功能代碼 P業(yè)務(wù)處理 Q業(yè)務(wù)查詢 C業(yè)務(wù)統(tǒng)計(jì) S系統(tǒng)維護(hù) w_功能代碼_拼音縮寫(xiě)（4）、用戶對(duì)象：uo_拼音縮寫(xiě)、英文（5）、管道： p_拼音縮寫(xiě)、英文（6）、查詢： q_拼音縮寫(xiě)、英文（7）、數(shù)據(jù)窗口：功能代碼 P業(yè)務(wù)處理 Q業(yè)務(wù)查詢 C業(yè)務(wù)統(tǒng)計(jì) S系統(tǒng)維護(hù) d_拼音縮寫(xiě) （8）、控件： 系統(tǒng)默認(rèn)的XXX_ + 拼音縮寫(xiě)、英文2. 程序的書(shū)寫(xiě)規(guī)則1) 保留字、特殊字符系統(tǒng)所定義的98個(gè)保留字不能作為標(biāo)識(shí)符，都必須大寫(xiě)。對(duì)于特殊字符必須用波浪號(hào)（）引用。2) 外部函數(shù)的聲明外部函數(shù)是指使用其它語(yǔ)言（PB以外的語(yǔ)言）并保存在動(dòng)態(tài)庫(kù)中的函數(shù)。有兩類外部函數(shù)要聲明：（1）、全局的外部函數(shù)；（2）、局部的外部函數(shù)。從返回值的角度來(lái)看有兩類函數(shù)：（1）、有返回值（即通常意義上的函數(shù)）；（2）、沒(méi)有返回值（即通常的過(guò)程）。帶返回值的外部函數(shù)的聲明：(在應(yīng)用中聲明時(shí)必須寫(xiě)在一行上)ACCESS FUNCTION retype funname (REF datetype arg1,) LIBRARY “l(fā)ibname” ALIAS FOR “extname”帶返回值的外部函數(shù)的聲明：(在應(yīng)用中聲明時(shí)必須寫(xiě)在一行上)ACCESS SUBROUTINE retype funname (REF datetype arg1,) LIBRARY “l(fā)ibname” ALIAS FOR “extname”說(shuō)明：（1）、ACCESS 在局部外部函數(shù)中指明訪問(wèn)的范圍，有效值是PUBLIC、PRIVATE、PROCTECTED； （2）、FUNCTION、SUBROTINE是保留字必須大寫(xiě)； （3）、rettype外部函數(shù)的返回類型； （4）、funname 是動(dòng)態(tài)庫(kù)中定義的函數(shù)名稱； （5）、REF 是傳參方式； （6）、LIBRARY 保留字； （7）、ALIASFOR保留字，給外部函數(shù)加個(gè)別名；（8）、例子： FUNCTION Uint waveOutGetNumDevs() LIBRARY “WINMM.DLL”3) 操作符操作符代表符號(hào)化的運(yùn)算，分為四類：算術(shù)操作符、關(guān)系操作符、邏輯操作符、連接操作符。由于操作符有優(yōu)先級(jí)，所以在進(jìn)行符號(hào)運(yùn)算時(shí)一定要合理運(yùn)用“（）”進(jìn)行調(diào)度，以達(dá)到預(yù)期目的。4) 賦值語(yǔ)句賦值語(yǔ)句用于變量和對(duì)象屬性的賦值，這是程序中使用最頻繁的語(yǔ)句。語(yǔ)法格式： variablename = expression說(shuō)明： variablename 是變量或?qū)ο髮傩?expression 是表達(dá)式，一定要注意類型的匹配、兼容，以及數(shù)據(jù)的四舍五入造成的數(shù)據(jù)誤差。5) 直接數(shù)值使用的禁止在程序中直接使用數(shù)值的編程方法，絕對(duì)禁止使用。盡量使用定義或參數(shù)設(shè)定，其原因如下：l 在將來(lái)變更的時(shí)候，需要修改源文件，或者比較導(dǎo)致修改比較復(fù)雜，而容易產(chǎn)生漏改等錯(cuò)誤。l 光從數(shù)值上來(lái)看的話，不容易明白其含義。對(duì)這種定數(shù)命名時(shí)，必須采用望其名通其意的名稱來(lái)全局或局部的常量定義。在程序中使用該常量。例：CONSTANT Int gi_length = 256CONSTANT Strig ls_person = 0116) 腳本和函數(shù)的書(shū)寫(xiě)格式 （1）、注釋無(wú)論函數(shù)也好，數(shù)據(jù)結(jié)構(gòu)也好，必須有相應(yīng)的注釋。注釋的目的，是為了將來(lái)軟件維護(hù)的時(shí)候，即使不看源程序，只看注釋的內(nèi)容，也能夠充分理解。注釋主要記述以下幾個(gè)方面的問(wèn)題： 功能，設(shè)計(jì)說(shuō)明，限制事項(xiàng)，邊界條件，假定或潛在的問(wèn)題。注釋不是程序語(yǔ)句的改頭換面，而是從更高的一個(gè)層次來(lái)闡述說(shuō)明。注釋在下述場(chǎng)所必須追加；1) 所有函數(shù)的開(kāi)頭2) 主要變量定義的后頭3) 給表字段、數(shù)據(jù)窗口列賦值的代碼后一定要注釋字段的中文含義4) 事件、函數(shù)內(nèi)部的變量，和參數(shù)的定義處5) 各個(gè)函數(shù)、事件中關(guān)鍵處理塊的開(kāi)頭A、 在應(yīng)用OPEN事件的開(kāi)頭，下述著作權(quán)表示的注釋要寫(xiě)。/ Copyright ZhongYa(NANJING) COMMUNICATION CO. 1999/ All Rights Reserved 。Writed By Round-The-World Developer/ 開(kāi)發(fā)工具: PowerBulider 、Ms-SqlServer 7.0/ 時(shí) 間: XXXX年XX月XX日/ 說(shuō) 明: /對(duì)于一般的事件也可以加入如上的注釋。/ 功能說(shuō)明：/ 變更記錄: 變更或版本更新的時(shí)候/ 日期 版本號(hào) 變更者名 變更內(nèi)容/ 2000/01/01 1.0 MR.dess 開(kāi)發(fā)/ 2000/02/05 2.0 Mr.chen 修改入口參數(shù)名稱/B、 在函數(shù)的開(kāi)頭，加入如下格式：/ 函數(shù)名稱: f_XXX / uf_XXX / mf_XXX / wf_XXX/ 目的用途: / 作用范圍: PUBLIC / PRIVATE / PROCTECTED/ 輸入?yún)?shù): DataType ab_boolean/ 返回參數(shù): DataType Y when ab_boolean is true/N when ab_boolean is false/ 變更記錄: 變更或版本更新的時(shí)候/ 日期 版本號(hào) 變更者名 變更內(nèi)容。/ 2000/01/01/ 1.0 MR.dess 由于版本更新，對(duì)函數(shù)返回類型/ 進(jìn)行更改/ 2000/02/05 2.0 Mr.chen 修改入口參數(shù)名稱/ C、變量及參數(shù)的注釋對(duì)于一些主要的變量、數(shù)據(jù)結(jié)構(gòu)定義，要說(shuō)明它是什麼樣用途的定義，以及如何被使用的。例： Int li_id;/* Process ID*/String ls_jobid /* Job ID*/ D、關(guān)鍵處理塊的注釋對(duì)于關(guān)鍵處理塊的說(shuō)明，要從詳細(xì)的設(shè)計(jì)層次來(lái)闡述。而不是簡(jiǎn)單的程序語(yǔ)言的改頭換面，那樣只能使注釋單調(diào)煩瑣。 E、給表字段、數(shù)據(jù)窗口列賦值的代碼后一定要注釋字段的中文含義ids_cfje.SetItem(ll_insertrow,cfh,as_cfh) /處方號(hào)ids_cfje.SetItem(ll_insertrow,cflb,ls_tsfl) /處方類別(普通、毒麻處方)ids_cfje.SetItem(ll_insertrow,je,ldc_sl * ldc_lsj) /金額ids_cfje.SetItem(ll_insertrow,jelb,ls_jelb) /金額類別ids_cfje.SetItem(ll_insertrow,ts,ll_ts) /帖數(shù)(草藥處方)ids_cfje.SetItem(ll_insertrow,fyzd,gs_zdh) /發(fā)藥站點(diǎn)（2）、數(shù)據(jù)類型、PB函數(shù)名稱的書(shū)寫(xiě)嚴(yán)格按PowerBuilder 系統(tǒng)的寫(xiě)法，基本是具有獨(dú)立的意義的詞或單詞首字母大寫(xiě)，其它小寫(xiě)，例如：MessageBox(),SetPointer(Arrow!)（3）、續(xù)行通常情況下，PowerScript 的一條語(yǔ)句書(shū)寫(xiě)在一行。語(yǔ)句書(shū)寫(xiě)完畢后，按ENTER鍵轉(zhuǎn)到下一行，開(kāi)始下一條語(yǔ)句，有時(shí)，為了閱讀的方便，需要把一條語(yǔ)句寫(xiě)在多行上，采用續(xù)行符“&”，例如：Messagebox (用戶對(duì)象外部函數(shù),初始化用戶對(duì)象外部函數(shù)發(fā)生一個(gè)錯(cuò)誤rn +& 在這個(gè)應(yīng)用中將無(wú)法無(wú)正確進(jìn)行外部調(diào)用”)（4）、縮進(jìn)格式程序必須采用縮進(jìn)格式。（5）、控件的繼承系統(tǒng)中所用的控件全部從公用庫(kù)中繼承，若公用庫(kù)中沒(méi)有所需的控件時(shí)請(qǐng)通知有關(guān)負(fù)責(zé)人在核心庫(kù)或公用庫(kù)中進(jìn)行增加，不能自行處理。控件中的文字一律以公用庫(kù)中的命名為準(zhǔn)，不能私自改動(dòng)，不得以時(shí)要求通知有關(guān)負(fù)責(zé)人進(jìn)行處理。3. 部分編碼、標(biāo)志的規(guī)則說(shuō)明對(duì)于數(shù)據(jù)庫(kù)中BM 或具有BM含義的字段一律以“編碼”為中文名，對(duì)于數(shù)據(jù)庫(kù)中的BZ或具有BZ含義的字段一律以“標(biāo)志”為中文名。對(duì)于可枚舉的變量一律以數(shù)據(jù)庫(kù)中定義的枚舉值和編碼為準(zhǔn)，不得私自設(shè)定。4. 代碼的變更軟件進(jìn)行修改的時(shí)候，修改的原因和改動(dòng)說(shuō)明，為了讓別人能夠明白，必須加以一定的注釋。而這種做法的目的有以下的重要意義：1) 錯(cuò)誤問(wèn)題發(fā)生的時(shí)候，可以幫助快速定位問(wèn)題的發(fā)生點(diǎn)。2) 對(duì)于軟件的版本更新管理有重要的意義。對(duì)于變更的地方，必須追加滿足下述條件的注釋。1) 注釋要覆蓋變更部分的整體范圍。因此，對(duì)于每個(gè)變更部分的開(kāi)始和結(jié)束，都要追加以下的注釋。/* Zhang 于2000.02.19 因 xxxxxxxxxxxxxxx作修改/刪除/增加 */ ./* 修改/刪除/增加結(jié)束 */此種注釋，最好對(duì)于比較大程度范圍的變更比較有效。 在有很多細(xì)微的變更的地方，可以采用以下注釋方式。/* Zhang 于2000.02.19 修改 gb_Status = FALSE */gb_Status = TRUE或者/* Zhang 于 2000.02.19 因有bug lack 作了修改 */ li_count = dw_person.OBJECT.countli_row;/* li_count = dw_detail.OBJECT.countli_rows; */2) 變更的時(shí)間以及版本號(hào)要記錄在版本發(fā)行以前如果作變更，不需要加入版本號(hào)。3) 變更部分的注釋格式要統(tǒng)一這樣可以使用編輯工具或者檢索工具，把所有的變更沒(méi)有遺漏地檢出。所以使用一定的關(guān)鍵詞是有必要的。4) 變更的位置，要一目了然要求注釋的格式是醒目并且整齊。5) 變更方法由于變更后經(jīng)常要參照變更前的源程序，考慮到這種情況，可從下述的三種變更方法中選擇一個(gè)最合適的，在項(xiàng)目中判斷。 A、源程序必須留下。利用條件編譯能清楚的看見(jiàn)變更前后的源程序，且可以簡(jiǎn)單地進(jìn)行變更前后的切換。/* Zhang 于 2000.02.19 因有bug lack 作了修改 */*變更前的源程序xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx;*/修改開(kāi)始變更后的源程序xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx; /修改結(jié)束B(niǎo)、利用版本管理。對(duì)于需要變更的源程序，直接給予變更。然后利用版本管理工具來(lái)管理各個(gè)階段版本的源程序?；蛘咧皇呛?jiǎn)單地把原有的程序拷貝到另一個(gè)目錄中，在必要的時(shí)候，在進(jìn)行文本文件的對(duì)比，以明確其差異。但也存在一個(gè)問(wèn)題，即不容易知道是否是新還是舊版本。5. 附錄 例程序1、函數(shù)范例：/ 函數(shù)名稱: f_profile_s