《編寫可維護的JavaScript》讀書筆記之自動化-檔案和目錄結構
檔案和目錄結構
在開始構建你的系統之前首先要確定如何組織你的檔案和目錄。而檔案和目錄的結構取決於專案型別。
最佳實踐
拋開專案型別不說,總有一些適合於 JavaScript 檔案和目錄結構公用的最佳實踐。
一個檔案只包含一個物件
- 概念:特指每個 JavaScript 檔案應該只包含一個 JavaScript 物件的程式碼。
- 優點:
- 程式碼更易維護。
- 降低了多個開發者同時修改同一檔案的風險。
- 檔案數量增加,版本管理工具進行檔案合併時衝突的可能性越小(檔案越少,單個檔案的內容越多,版本管理工具進行檔案合併時衝突的可能性越大)。
- 初衷:讓不同的人維護各自不同的檔案,即完全避免多人維護一個檔案的可能。
相關檔案用目錄分組
- 概念:將多個相關聯的物件放在同一個目錄下。
- 優點:有助於開發者更容易定位功能(所在的程式碼片段)。
保持第三方程式碼的獨立
- 概念:任何不是你寫的,或者不是由你維護的程式碼都應當獨立於專案工程(source control)之外。
- 推薦:不引入第三方 JavaScript 類庫,直接從 CDN 載入它們。或者把這些檔案單獨放置在專案工程中的一個目錄裡。
確定建立位置
- 建立後的 JavaScript 檔案應該放置在一個完全獨立的目錄裡,而且不應該提交到專案工程中。
- 網站應當是可配置的,使用編譯後的目錄而非原始碼目錄。
- 不要把編譯後的內容提交到原始碼工程裡,這一點非常重要。因為編譯後的內容都是成型的“工件”,在最終被部署上線之前,可能會被很多人多次編譯建立。部署過程應當通過編譯產生可最終釋出的成品,是可以直接部署上線的。
保持測試程式碼的完整性
- 概念:JavaScript 測試程式碼也應該一併提交到專案工程中的一個顯眼位置。這可以讓開發人員很容易注意到遺漏測試的情況。
【說明】:如果你當前工作的 JavaScript 檔案是一個大型網站或者 Web 應用的一部分而不是一個獨立的 JavaScript 專案,檔案和目錄的結構會有些許不同。整個目錄結構基本上由服務端使用的框架所決定。即使整個專案結構隨著專案的不同千變萬化,但始終會有一個單獨的目錄專門用來放置前端程式碼。
基本結構
JavaScript 目錄下邊放置如下三個主要目錄是當下一種很流行的做法。
- build:用來放置最終構建後的檔案,理想情況下這個目錄不應該提交。
- src:用來放置所有的原始檔,包括用來進行檔案分組的子目錄。
- test 或者 tests:用來放置所有的測試檔案。通常包含一些同源程式碼目錄一一對應的子目錄或檔案。
【說明】:開發環境和構建過程很大程度上決定著你會選擇什麼形式的結構。好的結構可以縮短構建的時間並且不會讓開發人員在新建檔案的時候糾結於放在哪裡。
案例展示
- CSSLint:
csslint
.git
build
demos
lib
npm
release
src
cli
core
formatters
rules
worker
tests
core
css
formatters
rules
【說明】:build 目錄從不提價,release 目錄始終包含最新的穩定發行版本。src 目錄下有一些按功能劃分的子目錄。tests 目錄的結構同 src 目錄的結構一一對應,所以 src/core/CSSLint.js 的測試程式碼即為 test/core/CSSLint.js。
- jQuery
jquery
build
speed
src
ajax
sizzle
ajax.js
attributes.js
callbacks.js
core.js
css.js
data.js
deferred.js
dimensions.js
effects.js
event.js
exports.js
intro.js
manipulation.js
offset.js
outro.js
queue.js
sizzle-jquery.js
support.js
tracersing.js
test
data
qunit
unit
ajax.js
attributes.js
callbacks.js
core.js
css.js
data.js
deferred.js
dimensions.js
effects.js
event.js
exports.js
manipulation.js
offset.js
queue.js
selector.js
support.js
tracersing.js
【說明】:jQuery 也採用了這種結構形式。唯一不同的就是 jQuery 把所有的原始檔都直接放在了 src 目錄下,而沒有每個都建立子目錄。子目錄保留用來存放核心特性的資原始檔和擴充套件。test 目錄存放著跟原始檔名字相同的測試程式碼。比如 src/ajax.js 的測試程式碼即為 test/ajax.js。
- Dojo
dojo
_base
_firebug
cldr
data
date
dnd
fx
io
nls
resources
rpc
selector
store
tests
_base
cache
data
date
dnd
html
io
nls
resources
store
uacss
window
aspect.js
back.js
...
cache.js
dojo.js
date.js
【說明】:Dojo 採用了同 jQuery 類似的結構心事。其中一個很大的不同是 Dojo 根目錄下沒有 src。而是頂層目錄直接包含了所有的原始檔和用來放置核心特性資原始檔和擴充套件的子目錄。tests 目錄跟頂級目錄的結構一一對應,所以 tests/date.js 即 date.js 的測試程式碼。
- YUI
yui3
build
sandbox
src
anim
app
arraysort
js
arraysort.js
meta
tests
arraysort.html
build.properties
build.xml
HISTORY.md
README.md
async-queue
【說明】:修改了原有的結構,src 目錄下的每個子目錄都代表一個單獨的 YUI 模組,而且每個模組都至少有以下 4 個子目錄。
- docs:文件目錄。
- js:JavaScript 原始檔目錄。
- 用以存放模組元資訊(metadata)。
- tests:用以存放模組的測試程式碼。
【注意】:YUI 中的測試檔案可能是 HTML 檔案或者 JavaScript 檔案,因此準確地說 tests 目錄中包含的內容因模組而異。一般而言,至少有一個檔案的名稱同源檔案一致。所以 tests/arraysort.html 或者 tests/arraysort.js 就是 js/arraysort.js 的測試程式碼。