Larvata 的命名原則,範圍包括:專案、目錄、檔案、應用程式內部設定等。
專案命名的應用範圍包括:Redmine、Bitbucket、Gitlab、Github 等。
- 絕對不以數字作為名稱開頭。
- 名稱保持全小寫英文 (a-z)、連接線 (-)、數字 (0-9)。
- 格式為:客戶-年份-代碼,其中年份可省略。
- 禁止使用空白字元。
- 範例:larvata-awesome-app、client-2018-good-project
- 盡量不以數字作為檔案名或目錄名開頭。
- 名稱保持中文、英文、底線 (_)、數字 (0-9)。
- 英文單詞之間用底線 (_) 連接,英文與數字之間不強制是否有連接底線。
- 禁止使用空白字元。
- 範例:larvata_logo.png、backup2016/、客戶_合約書.doc、客戶_報價單.doc
- follow function list name, translate all to english first
- decide and name all controller
- fill in all actions in controller
- check ajax call actions
- generate blank all related view files
- check partial view needs, generate more partial for action pages
- decide page class name
- decide big or reuseable component class name
- make css file and partial files
- generate page related js files
- 關閉自動更新版本。
- 禁止手動更新版本。
- 檔案命名 ...?
- 圖層命名 ...?
- Image 與 Container 命名使用全小寫英文 (a-z)、底線 (-)、數字 (0-9)
- 英文單詞之間用底線 (_) 連接,英文與數字之間不強制是否有連接底線。
- 禁止使用空白字元。
- 範例:larvata_mysql,larvata_nginx
- 資料庫、資料表、欄位名稱使用全小寫英文 (a-z)、底線 (_)、數字 (0-9)
- 英文單詞之間用底線 (_) 連接。
- 英文與數字之間直接連接。
- 禁止使用空白字元。
- 範例:larvata_database,users,first_name
- 依照專案類型建立適當的 .gitignore。
- Branch 名稱保持全小寫英文 (a-z)、減號 (-)、數字 (0-9)。
- Branch 名稱的英文單詞使用減號 (-) 連接。
- 嚴格遵守 git-flow 流程。
- git-flow 分:git-flow, git-flow-avh 目前公司內部還沒有定論 ...
使用 scoped branch name 是理想且合理的命名方式,亦即在分支名中使用 /
。
- 重構的 branch 一律以 refactor/ 為前綴開頭
- 程式整理的 branch 一律以 syntax_enhancement/ 為前綴開頭
- 套件升級及相關設定的 branch 一律以 upgrade/ 為前綴開頭
範例:
feature/my-awesome-feature
fix/issue-666
release/0.1.0
note: git-flow 也採用此法來命名分支。
建議使用 /[a-zA-Z0-9-]+/
作為 feature/{placeholder}
分支使用之字元,並應具有合理語意、且動詞一律採用現在簡單式。
命名邏輯範例:
- IF 有相關 issue/pull-request/redmine-issue
- issue
後綴採用
issue-%d
格式;例如fix/issue-26
- pull-request
後綴採用
pr-%d
格式;使用例為 patch some problems derivative from another pull-request - redmine-issue
後綴採用
redmine-%d
格式;例如feature/redmine-20324
- issue
後綴採用
- ELSE
- 採用直接關係功能導向語意作為命名方向,範例:
feature/update-footer-copyright
feature/drop-contact-page
- etc.
- 採用直接關係功能導向語意作為命名方向,範例:
使用如:
master
develop
feature
hotfix
release
- ...
等,建立一套分支前綴作為第一原則。
如團隊引用 github-flow,討論是否採用 username-scoped-branch-name 配合 pull-request 作為主要分支命名方式
- 方便往後了解演變,單一 commit 完成單一主旨
- 如果有相關的 issue 需以 refs #issue 編號為前綴開頭
Larvata 程式碼風格規範,Larvata 內部對各種程式語言的編寫規範。
其應用原則有以下幾條:
- 遵循該程式語言的社群標準。
- 若使用的 Framework 另有其規範,則以該規範為準。
- 自行訂立的風格規範。
- 原則的權重以排序越後的越重 (後者覆蓋前者)。
所有人員都應該安裝 EditorConfig 作為編輯器風格控制器:
EditorConfig 外掛下載
並使用 Larvata 的 EditorConfig 設定檔,下載另存到:~/.editorconfig
。
- http://mmdays.com/2007/04/24/coding-style/
- http://sideeffect.kr/popularconvention/
- https://github.com/showcases/clean-code-linters
- 以 http://codeguide.co 規範為基礎。
- 所有 *.html 檔案以 4 個空白為縮排。
CSS 樣式用途,使用全小寫英文與底線連接,例如:
red_text
Hack 調整用途,使用全小寫英文與底線連接,並加上說明描述與後綴:-hack
,例如:
red_text_xs-hack
JS 用途,使用全小寫英文與中線連接,並加上前綴 js-
,例如:
js-change-color
使用全小寫英文與中線連接,例如:
my-only-one-div
main frame file:
- rails: /app/views/latouts/application.html.erb
- yii2: /views/layouts/main.php
page file:
follow controller name and action name(use yii2 as sample) controller/action
- controller/newsController/indexAction -> view/news/index.php
- controller/newsController/createAction -> view/news/create.php
partial page file
controller/_action_part
- controller/newsController/indexAction -> view/news/index.php
- controller/newsController/indexAction?tab=all -> view/news/_index_all.php
- controller/newsController/indexAction?tab=past -> view/news/_index_past.php
- 以 Airbnb CSS 規範為基礎。
- 所有 *.css,*.scss 檔案以 2 個空白為縮排。
以 Airbnb JavaScript 規範為基礎。- 以 StandardJS 規範為基礎。
- 所有 *.js 檔案以 4 個空白為縮排。
- 寫於view內的js應該都置於page的最外層,include檔案內勿撰寫獨立inline js, 共用partial view檔的js應獨立拆出成為共用檔案
當按鈕被使用者click時,需要依照觸發後的行為做相對應的處置
此時需注意按鈕在當次操作行為完成前不能被重複click,故必須處置的pattern可以是:
click按鈕時使用.js-lock class有無判斷來鎖定後續的行為是否可以在事件完成前被重複觸發
$(btn).click(function(){
if($(btn).hasClass('js-lock')){
return false;//如果有lock class就不能再繼續行為
}else{
$(btn).addClass('js-lock')//開始鎖定按鈕
//繼續發送的ajax行為直到行為結束
$(btn).removeClass('js-lock')//解除鎖定按鈕
});
實務上modal觸發常常需要抓取資料填入modal內,故需要在click按鈕觸發modal同時執行其他獲取資料行為
click btn, 綁定一個事件獲取相關資訊後回填至modal結構內,modal內容部分由半透明變回正常不透明
$(btn).click(function(){
$(modal-body).css(opacity:0.3);//modal內容的部分刷淡讓使用者知道內容尚未ready
$(modal-body).addClass('js-lock')//也可以把整個body跟送出按鈕等等加上lock
//獲取資料ajax或是由頁面內(通常是列表)data-xxx來獲取資訊
//將資料填回modal-body內的部分(通常使用id來綁定欄位)
$(modal-body).css(opacity:1);//資料備齊了,可以把資訊變回正常顏色
$(modal-body).removeClass('js-lock')//最後解除所有可以按的畫面與按鈕的lock,使用者可正常操作modal內容
});
site scope js file:
put in one or two general js file
- application.js
- common.js
- init.js
page scope js file:
follow controller/action_part role
- controller/newsController/indexAction -> js/news/index.js
- controller/newsController/indexAction?tab=all -> js/news/index_all.js
- 以 PSR-2 規範為基礎。
- 所有 *.php 檔案以 2 個空白為縮排。
- 以 PEP-0008 規範為基礎。
- 所有 *.py 檔案以 4 個空白為縮排。
- 以 Ruby Style Guide 規範為基礎。
- 以 RuboCop 作為語法檢查工具。
- 所有 *.rb 檔案以 2 個空白為縮排。
- Rails 以 Rails Style Guide 規範為基礎。
- 禁止使用 SQLite 作為開發環境、生產環境的資料庫。
- 以 raywenderlich.com 規範為基礎。
- 所有 *.swift 檔案以 2 個空白為縮排。
- 皆採用小駝峰式命名法 (lowerCamelCase)
- Resource groups 命名規則:類型+環境(-商戶)
- 範例:sportServiceStaging、sportDevopsStaging-larvata
- 服務命名規則:應用+序號+環境(-商戶)(-子元件)
- 範例:ap1Staging、rproxy2Staging-larvata-disk2
- Virtual Network 命名規則類似 Resource groups,但是以 vnet 作為前綴
- 範例:vnetSportServiceStaging、vnetSportServiceStaging-larvata
- 禁止使用空白字元
- 序號起始為 1