Transcript 2014-08-05-CodingStandard

Coding Standard
By Cwlin IDIC
Why Coding Standard?
• 程式語言本身已經有語法格式的規則，但實際在開發時每
個人寫出來的程式碼差異可能很大
• 不同人寫的程式碼可能會因為習慣的好壞與不同，導致所
搛寫出來的程式碼其他人並不容易理解
• 系統開發通常是需要多人協同開發完成的，有統一的寫法
可以避免程式難以理解、且易於維護
• 為了要讓所有人有一個可以遵循的規則與標準，便會製定
程式碼規範
What is Coding Standard?
• 程式碼規範會基於以下幾個原則去規範
• 易於理解
• 易於擴充
• 易於除錯
• 常見的程式碼規範包含以下部份，由基礎至詳細
•
•
•
•
•
•
•
•
•
目錄結構
檔案格式
命名規則
縮排與行字數限制
函數呼叫
類別定義
函數定義
陣列
註解
What is Coding Standard? (續)
• 不同程式語言，不同的開發環境，所規定的程式碼規範也
會不同，但都大同小異
• 本門課主要以 PHP 為例，由於使用 Netbeans 開發，
Netbeans 已經可以自動格式化程式碼，所以在此僅說明以
下部份
• 目錄結構
• 檔案格式
• 命名規則
目錄結構
• 目錄結構主要牽涉到一個專案的檔案要如何分門別類，會
依照實際使用的情況規劃適合的目錄結構，讓開發人員能
夠易於管理程式
• 目錄結構沒有一定的標準，不同的專案有不同的特性，所
規劃出來的目錄結構會有所不同，最重要的是易於管理及
易於擴充
• 要先了解專案可能會用到那些檔案，以網頁程式設計，可
能使用的檔案如下
•
•
•
•
•
HTML
JavaScript
圖片
樣版
PHP
目錄結構
• 規畫適合 MVC 架構的目錄結構
• Project
•
•
•
•
•
•
/install
/scripts
/styles
/images
/library
/view
• /templates
• /model
• /controller
• /actions
• /index.php
放置資料庫 SQL 檔案
放置網頁用的JavaScript 檔案
放置網頁用的CSS 檔案
放置網頁用的圖片
放置 PHP 使用的套件
放置 PHP View
放置 PHP 樣版(.tpl)
放置 PHP Model
放置 PHP Controller
放置 PHP Controller Action
主程式
• 物件導向程式設計通常一個檔案代表一個 Class，會直接使用
Class 名稱做為檔案名稱
檔案格式
• 依照不同的程式環境、程式特性，所使用的檔案格式也會
有所不同
• 以 Java 為例，Java 標榜跨平台、跨語系，因此所採用的檔
案編碼格式便以 UTF-8 為主
• PHP 並沒有一定要使用 UTF-8 編碼，最早以前 Unicode 還
不是那麼通行的年代，大部份人會選擇中文編碼 big5，俗
稱的大五碼
• 但由於網頁的全球化，現在開發網頁程式，為了要能夠使
用多國語系，大都直接採用 UTF-8
命名規則
• 在程式碼中，從基本的變數、函數到類別、方法、屬性，
都會需要程式設計師去命名
• 為了讓程式易於閱讀、易於維護、易於辨識、避免衝突，
那麼命名規則就很重要
• 通常程式語言會有自己的命名規則
• C/C++ 使用 _ 符號區隔單字，如: out_of_range
• Java 使用大小寫區隔單字，如: OutOfRange
• 由於像雙峰駱駝又稱 CamelCase
• 開發的專案也可以自行要求命名規則
• 目前大多數的命名規則主要以 C/C++、Java 兩種標準為主
• Java 的命名規則又尤其常用於物件導向程式設計
命名規則 (續)
• 命名規則通常包含以下範圍
•
•
•
•
常數
全域變數、函數
命名空間與類別名稱
類別常數、屬性及方法
命名規則-常數
• 常數的用途是在程式中定義不會任意更改的值，如:
• PI = 3.1415926
• 為了突顯常數，常數的命名會以全部大寫表示，以 _ 符號
區隔單字，如:
• DB_DATASOURCENAME
• SERVICES_AMAZON_S3_LICENSEKEY
命名規則-全域變數
• 名稱必須分類名稱開頭，如 PEAR，後接著實際的變數名稱
• $PEAR_destructor_object_list
• $PEAR_destructor_object
• 全域的變數很容易於其他全域變數衝突，若在開頭沒有特
別區別，就很容易發生易料之外的問題
• 在有區別的情況下也較容易辨識變數的用途
• 這種命名規則，是延伸以前 C 語言沒有使用物件導向程式
設計時的規則，若採用物件導向程式設計，幾乎不會使用
到這個規則
命名規則-全域函數
• 名稱必須使用分類名稱開頭，如 PEAR，後接著實際的函數
名稱
• XML_RPC_serializeData()
• 全域的函數的名稱同全域變數的問題，很容易發生易料之
外的問題，因此會在開頭加上分類的名稱
• 函數名稱則以 CamelCase 方式命名
• 這種命名規則，是延伸以前 C 語言沒有使用物件導向程式
設計時的規則，若採用物件導向程式設計，幾乎不會使用
到這個規則
命名規則-類別
• 使用 CamelCase 命名
• Log
• NetFinger
• HtmlUploadError
命名規則-類別屬性與方法
• 使用 CamelCase 命名，第一個字小寫
•
•
•
•
$counter
connect()
getData()
buildSomeWidget()
• 私有的屬性與方法則會在前方加 _ 以區別
• $_status
• _sort()
• _initTree()
註解
• PHP 程式開發的註解方式通常使用 phpDoc 所制定的格式
• 使用 phpDoc 所制定的格式，一方面有標準的註解方式，
另一方面可以便於未來產生 API 文件，Netbeans 編輯器也
會根據該註解自動提示訊息
/**
* 存入版型檔案
* @param string[] $imgPaths 圖片路徑
* @param string $cssContent CSS 內容
* @param string $saveType 版型路徑
* @return boolean 回傳值說明
*/
private function saveTheme($imgPaths, $cssContent, $saveType) {
註解變數型態
• 由於 PHP 的特性，在使用變數時不需要宣告形態，雖然簡
單方便，但往往在使用函數時會因為不曉應該傳入的參數
型態造成困擾。
• 透過 phpDoc 格式註明型態可以讓呼叫函數時更易於辨識
函數所需的參數
• phpDoc 支援的基本型態有
• string, integer, boolean, array, resource, null, callable
• 若物件則直接使用類別名稱
• DateTime
• 若為陣列可表示為
• string[], integer[], DateTime[]
Netbeans 加入 phpDoc 註解
• 在函數上方輸入 /** 後按 ENTER 即會自動產生對應格式
Netbeans 重新命名
• 重新命名類別、函數、變數的動作叫做重構 Refactor
• Netbeans 支援 Refactor 功能可自動搜尋所有使用到該名稱
的地方一併重新命名
• 點選要重新命名的類別、函數、變數，當出現黃色區塊時
按 Ctrl + R
• 此功能固然方便，但也有可能損壞你的程式碼，使用時務必
先做好備份
作業
• 重新整理活動訊息模組以符號上述程式碼規範開發