軟件開發規範 v0.1
1 前言
爲了使軟件開發過程有章可循，保證軟件質量，加強開發管理。
2 開發管理
項目進度週報表格如下：
項目編號：
彙報人：
彙報日期：
項目進度詳細描述：
其他問題：
3 項目週期
司項目開發週期分爲以下幾個步驟：
步驟 說明 參與角色 生成文檔或程序（打*號爲可選）
可行性分析 對項目的技術，功能需求和市場進行調研和初步分析，確定是否需要立項開發。 部門主管核心技術員 可行性分析報告*技術調研報告*
立項 正式立項，由部門主管指定項目經理，項目經理制定初步計劃。初步計劃包括設計和開發時間的初步估算。 部門主管核心技術員 項目初步計劃
需求分析 對項目進行詳細的需求分析，編寫需求分析文檔。對於B/S結構軟件系統需要製作靜態演示頁面。需求分析文檔和靜態演示頁面需要通過部門主管審批才能夠進行到下一個步驟 項目經理項目核心小組 需求分析文檔靜態演示頁面項目計劃修訂版本
詳細設計 根據需求分析對項目進行詳細設計。詳細設計以後，項目經理同部門主管一起指定項目小組開發成員。 項目經理項目核心小組 詳細設計文檔項目計劃確定版本
開發 根據設計開發項目，由美工對操作界面進行美化。 項目經理項目開發員美工 項目計劃修訂版本*
測試 項目經理提交測試申請，由測試部門對項目進行測試。項目小組配合測試部門修改軟件中的錯誤。 項目經理項目開發員測試部 測試申請測試計劃測試報告
項目驗收 項目驗收歸檔 部門主管項目經理 項目所有文檔和程序
4 命名規範
4.3 jsp/html命名規範
jsp與html文件名全部小寫，並遵循如下的規範：
u 數據/內容顯示頁
名詞，多個單詞用下劃線分隔，要求能說明顯示內容的信息，爲避免衝突，可加上 “_list”。例如：
new_message.html 或 my_file_list.jsp
u 操作處理頁
命名格式：名詞_下劃線_動詞，例如：file_delete.jsp。
u 含frame頁面
<frameset>中<frame>的name屬性命名的格式是①xxx._②xxx_③xxx
①xxx部分用來標識當前頁面隸屬於整個系統中的哪一功能模塊。
如：屬於ebwebmail則被表示爲ebwebmail，其它情況依次類推。
②xxx部分標識當前頁面所要完成的功能。
如：完成用戶登錄的功能則被標識爲login，其它情況依次類推。
③xxx部分用來用來表示頁面在瀏覽器窗口所處的位置。
處於瀏覽器窗口的頂部則標識爲top，其它情況依次類推。
例如：ebwebmail_inbox_top.jsp
<frame> src屬性相應的文件名根據情況建議在原命名規範上用下劃線加上所處窗口的位置。
u javascript腳本方法
腳本函數都以①xxx_②xxx的方式命名。
①xxx對應頁面隸屬的模塊。
②xxx表示函數所要實現的功能(動賓結構)，多個單詞用下劃線連接。
例如：ebwebmail_send_mail()
模塊通用的腳本函數必須集合於一個js文件中，在頁面上通過<script language=”javascript” src=”url”></script>形式導入。js文件名命名使用模塊名，例如：ebwebmail.js。
如果項目已經提供了公共js腳本，則優先使用公共js腳本中提供的函數。
所有定義方法的<script>元素定義在<head></head>中或</body>後。
u javascript腳本內部變量與參數
單詞之間用下劃線分隔且全部小寫，例如：
var file_size。
u <form>表單name屬性
統一以“form_”開頭，其後加該表單所需收集的信息的作用或動作，例如：form_file_upload 或 form_send_mail。
u 表單elements
表單element的名稱以element需收集的信息標示命名，單詞之間使用下劃線分隔且全部小寫，例如：
<input type=”text” name=”username”>
<input type=”radio” name=”file_type”>
<textarea name=”content” rows=”5” cols=”40”>
u cookie命名
命名格式：模塊名_存儲信息名詞(多個單詞用下劃線分隔) ，全部大寫，例如：EBWEBMAIL_SORT_TYPE。
u window.open中name參數的命名
javascript的window.open方法中有一個name的參數，瀏覽器約定同樣的名字的窗口只能打開一個，如果程序間名字重複將相互衝突。如果不限制打開窗口數，可以指定‘’或“”（不是null），否則需要加上模塊名，例如ebwebmail_viewmail。
4.4 數據庫命名規範
數據庫表命名均遵循以下規範：
模塊名_存儲信息名詞(多個單詞用下劃線分隔)，全部小寫，例如：ebwebmail_message。
數據庫字段命名遵循以下規範：
存儲信息名詞(多個單詞用下劃線分隔)，全部小寫，例如：message_id。
5 文檔規範
1. 編寫文檔目前主要使用的工具是Word（項目計劃文檔例外，需要使用Project製作），輔助使用的工具有Visio，PowerPoint，ERWin等。
2. 文檔務必保持段落格式整齊，文字字體，顏色，大小統一。
3. 如果需要摘引html頁面中的內容，不能直接從html中粘貼過來（會在word文檔中留下html格式），而必須先去除格式，例如：先粘貼到notepad中。
4. 務必注意中英文標點符號，文檔正文一概使用中文標點符號。
5. 如果需要在文檔中插圖，不要使用word自帶的繪圖工具。可以選擇使用PowerPoint或visio。使用PowerPoint，選擇“插入”->“對象”->“Microsoft PowerPoint 幻燈片”。使用visio，需要另外建立visio文檔，繪製完以後粘貼到word中。
6. 數據建模使用ERwin工具，文檔中僅需要粘貼數據模型的邏輯視圖（logical view），另外還要附上表結構描述。
7. 修改他人文檔務必使用修訂模式，以便保留備修改的內容。使用修訂模式，選擇“工具”->“修訂”->“突出顯示修訂”，勾上“編輯時標記修訂”。
附：一些模版
ü Java類設計(class documentation)
聲明：
描述：
屬性：
1. property_name
聲明
說明
方法：
1. method_name
聲明
說明
參數
返回值
異常
注：
方法聲明中，如果遇到重載的方法，可以使用“|”表示可以接受不同類型的參數，例如：“String value | int value”；可以使用“[]”表示可選的參數，例如：“Object message[,Throwable t]”
ü Servlet設計(servlet document)
類名 接受參數列表 描述
ü 數據表設計(data modeling)
表名：some_table
說明：description
表結構：
字段名 類型 說明
6 代碼規範
6.1 Java源代碼規範
6.1.1 命名
u Package 的命名
Package 的名字應該都是由一個小寫單詞組成，例如：net.ebseries.modules。
此外，對於包名我們做如下約定：
1. 工具函數類包名前綴爲.util
2. Servlet類包名前綴爲.servlet
3. test case類包名前綴爲.test
u Class 的命名
Class 的名字必須由大寫字母開頭而其他字母都小寫的單詞組成，例如：DataFile或InfoParser。
u Class 變量的命名
變量的名字必須用一個小寫字母開頭。後面的單詞用大寫字母開頭，例如：debug 或 inputFileSize。
u Static Final 變量的命名
Static Final 變量的名字應該都大寫，並且指出完整含義，例如：MAX_UPLOAD_FILE_SIZE=1024。
u 參數的命名
參數的名字必須和變量的命名規範一致。
u 數組的命名
數組應該總是用下面的方式來命名：
byte[] buffer;
而不是：
byte buffer[];
u 方法的參數
使用有意義的參數命名，如果可能的話，使用和要賦值的字段一樣的名字：
SetCounter(int size)
{
this.size = size;
}
6.1.2 代碼格式
u 文件頭聲明
源文件的頭部需要一個history段，對於每次對源文件的重大改動，都需要在history段中註明。該段定義在package和import之間，例如：
／*****************************************************
* HISTORY
* 2002/01/29 Biz 創建文件
* 2002/02/19 kevin 增加新功能
*******************************************************/
u import順序
import包按一下順序：
1. jdk標準包
2. java擴展包（例如servlet，javamail，jce等）
3. 使用的外部庫的包（例如xml parser）
4. 使用的項目的公共包
5. 使用的模塊的其他包
每一類import後面加一個換行。
例如：
import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.mail.*;
import org.apache.xml.*;
import net.ebseries.*;
import net.ebseries.util.*;
import net.ebseries.ebwebmail.*;
u 代碼塊書寫格式
可以選擇以下任意一種代碼塊的書寫方式：
if (true){
//body
}
if (true)
{
//body
}
建議使用第二種書寫方式。如果是修改他人的代碼，必須使用代碼原來的書寫方式。
對於代碼塊過長，超過1屏以上，}後面要說明屬於那個代碼塊，例如：
if (i > 100)
{
//too many lines more than one screen
}// if (i > 100)
u 關於縮進
縮進使用4個連續空格，不要在源文件中保存tab字符， 請注意調整所用的IDE工具，打開將tab轉換爲空格功能。
u 頁寬
頁寬應該設置爲80字符. 源代碼一般不會超過這個寬度, 並導致無法完整顯示, 但這一設置也可以靈活調整. 在任何情況下, 超長的語句應該在一個逗號或者一個操作符後折行. 一條語句折行後, 應該比原來的語句再縮進4個空格。
u 操作符
操作符左右各用一個空格分隔。
例如：
int a = b;
if (a > 0);
u SQL語句
代碼中書寫的sql語句要求sql關鍵字全部大寫，表名和字段名小寫。例如：
SELECT user_id, name FROM account WHERE user_id > ? AND depart = ? ORDER BY name
u 類和方法定義
類定義或方法定義過長需要換行書寫，例如：
public class CounterSet
extends Observable
implements Cloneable
private PortletSet getPortlets( Portlets portlets,
RunData rundata,
boolean application,
boolean applicationsOnly )
{
}
6.1.3 註釋
public 和 protected的成員變量和方法必須寫javadoc註釋。超過1句以上的註釋使用中文書寫。對於代碼多於10行的private方法也要寫javadoc註釋。
對於代碼中的邏輯分支或循環條件需要書寫註釋，例如：
if (some condition)
{
//符合某個條件，應該這樣處理
}
else
{
//否則應該那樣處理
}
6.1.4 其他
u 關於屬性
類中的屬性不能定義爲public變量直接存取，而是定義成protect變量並編寫get/set方法，例如：
protect String myName;
public String getMyName()
{
return myName;
}
public void setMyName(String myName)
{
this.myName=myName;
}
6.2 jsp/html代碼規範
u jsp/html描述註釋
jsp/html頁面頂部必須存在一個基本描述註釋，包含功能描述、參數列表和歷史修改信息，例如：
<%--
/**************************************************
* NAME : file_download.jsp
* PURPOSE : 下載文件提示
* PARAMETERS :
* file_id - 文件ID號
* force ?C 是否強制下載
* HISTORY
* 2002/04/05 Hafele 創建文件
* 2002/06/07 tmp 增加強制下在功能
*************************************************/
--%>
u jsp頭格式
jsp頭部一般需要遵循以下格式：
<%@ page contentType="text/html;charset=gb2312" %>
<%@ page import="java.io.*" %> // jdk標準包
<%@ page import="javax.mail.*" %> // java擴展包
<%@ page import="org.apache.xml.*" %> //使用的外部庫的包
<%@ page import="com.sunrise..*" %> //使用的項目的公共包
<%@ page import=" com.sunrise.applications.*" %> //使用的模塊的其他包
<%@ include file="some.jsp" %> //include其他的jsp
<%
response.setHeader("Pragma","No-cache");
response.setHeader("Cache-Control","no-cache");
response.setHeader("Expires","0");
%> //一般jsp都需要防止緩存
u html格式
1. html頭一般需要遵循以下格式：
<head>
<meta http-equiv="Content-Type" content="text/html; charset=gb2312">
<title>some title</title>
<link rel="stylesheet" href="some.css" type="text/css">
<script language="javascript">
//some javascript
</script>
</head>
注意：必須指定一個有意義的<title>，嚴禁出現“Untitled”或“未命名”之類的<title>。
2. 所有html標籤使用小寫
3. html頁面一般需要設置一個背景色（一般是#FFFFFF）。
u html語法校驗
所有的jsp/html頁面需要能夠使用DreamWeaver正確打開（即html語法正確，沒有錯誤的標記）。
u 註釋
一般不使用html註釋，除非是有必要讓最終用戶看到的內容。對於包含JSP代碼的html塊，必須使用JSP註釋。對於沒有必要的註釋，在發行版本中必須移除。
u form屬於域的maxlength
對於text類型的輸入域，必須根據數據庫字段的長度設置相應的maxlength，例如數據庫類型是VARCHAR(64)，那麼maxlength是32（因爲中文瀏覽器對於中文也認爲是一個字符）。
6.3 其他規範
u 對於IDE的使用
目前暫不限制開發工具的使用，但是最後提交的代碼必須不依賴任何IDE，而需要可以使用ant完成所有的編譯工作。一般提交的代碼目錄格式如下：
/
|_dist（存放輸出的文件class文件）
|_lib（使用的庫）
|_src（源代碼）
|_docs（文檔）
|_wwwroot（頁面文件）
|_build.xml（ant的build文件）
|_changes.log（代碼版本和修改的日誌）
u 限制session的使用
在代碼中使用session需要聽取項目經理的意見，項目經理需要在設計文檔中登記項目中所有使用到的session的名字和作用。
u 限制外部包的使用
開發員如果需要使用一個外部包需要聽取項目經理的意見。在項目經理批准以前，嚴禁擅自使用一個外部的包。<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />