PB命名規(guī)范.doc

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