～雨雪紛飛(Blog)～: (ㅍ_ㅍ) 整理一下自己的 Coding Style

看到成為 CSS 團隊的一員：CSS 團隊開發的最佳實踐和Google 的 Coding Style，突然想要整理一下自己的 Coding Style

Coding Style

變數命名

基本原則是橫線（-） > 駝峰 > 底線

橫線指的是 $project-item 這種命名方式，比較常見於前端，HTML 的 Class、id、CSS 都可以以此命名

即儘量以下面的方式命名

<div id="product-list" class="item-list"/>

$list-main-color: #aaa;
.item-list{
	color: $list-main-color;
}

但大部分的程式語言其實都不支援這種命名法，不支援的程式就以駝峰式命名

function(numOfList: Number){
	var projectItemList = [];
	for(var i = 0; i < numOfList; i++){
		projectItemList.push(new Product())
	}
	// ...
}

最後的底線其實要用到的機會不大，只有在 const variable 或 C 語言才會遇到
不過通常我會儘量採用駝峰就是

之所以有會這樣，是以兩者作為考慮

閱讀方便
撰寫 Code 方便
該程式語言默認習慣

在打變數時，橫線之所以第一，主要是能用橫線的程式語言，三者都符合。打 product-list 和 productList，其實 2. 這點都差不多，但是相較駝峰，在閱讀上還是橫線更方便（文字不會黏在一起、佔具面積小，大腦能當成普通英語來閱讀）。
此外，能使用橫線的其實很少，主要是 XML 和 CSS 這些，而這些的情況，事實上用橫線也是比較符合默認習慣的。像是 HTML5 的 data-attr*，就是採用橫線來命名變數的。至於 id 、 css class ，我看很多框架，例如 bootstrap、fontawesome 也是採橫線命名。

而駝峰相對於另外兩者，閱讀上比較吃虧。但排第二的原因是因為 2. 和 3. 。很多人寫程式都習慣駝峰命名這點就不提
駝峰撰寫方便，是因為打大寫比打底線步驟少，例如 productList 和 product_list ，前者打完product後，Shift + L + ist，後者是Shift + _ + L + ist，底線的位置其實打久了很不方便，所以駝峰比底線優先多了

Tab & Space

程式界最古老也最永恆的話題 XD

我個人是 Tab ，理由是

Tab 本身就是設計給縮進用的
當你鍵盤當前位置是縮進完後第一個字元，按下鍵盤的方向鍵會很不方便

第二點的意思是，假設我縮進如下：

if(a > 0){
	// TODO
}

如果我現在的位置在 if 和括號之間，按下↓鍵，以 Tab 排版就會是

ifI(a > 0){
	// TODO
}

變成

if(a > 0){
I	// TODO
}

如果以空格排版，則會是

ifI(a > 0){
         // TODO
}

變成

if(a > 0){
  I      // TODO
}

看起來沒什麼，但如果我今天按的是←、→，甚至Backspace←呢？
整個排版很快就能亂掉了！

當然，現在有很多 IDE 能自動處理這些問題，但 IDE 終究只是程式，不可能能完美處理每次的問題的！

另外要提一點，雖然很多人抱怨 Tab 和 Space 不可混用，但我認為下面幾種特殊情況是可以例外的（黃色為 tab；橘色為空格）

function (){
	if(a > b &&
	   (c > d || d == e)){
		// TODO 
	}
}

<div>
	<div id="sample-block"
	     class="alert-block small-block"
	     data-create-time="2018-01-01"
	     data-creator="John"
	     data-status="done" />
</div>

var query = "SELECT u FROM Product p                            "
          += "LEFT JOIN p.soldRecord AS s                       "
          += "LEFT JOIN p.owner AS u                            "
          += "WHERE u.id > 0                                    "
          += "  AND s.timd BETWEEN '2018-01-01' AND '2018-06-30'";
session.createQuery(query)
	.setMaxResult(10)
	.list();

簡單說就是

Tab 用以縮進
空格用以對齊

註解

基本上我對註解沒什麼要求，但儘量要能生成說明文件。

簡單說就是儘量要讓 JavaDoc、JSDoc 之類的能生成說明文件就對了！

多行註解

如果註解會有多行（尤其是說明文件用的註解最常見），則根據是 /* ...*/ 還是 // 來決定
如果是前者，則依照下面格式

/**
 * Reader provides sequential access to the contents of a tar archive. 
 * Reader.Next advances to the next file in the archive (including the first), and then Reader can be treated as an io.Reader to access the file's data.
 *
 * @param io Some object
 */

注意 @param 註解和說明文字之間空一行

另外註解是每行都以 * 來開頭

至於註解的位置，縮排和程式碼對齊，如下：

/**
 * Class for functions escaping and unescaping HTML text.
 */
public class HTML{
	/**
	 * Creates a new template and parses the template definitions from the named files. 
	 *
	 * @param files Files for parsing
	 */
	public void parseFiles(String ...files){
		// 中略
	}
}

特定語言

CSS / SASS / SCSS / LESS

檔案架構

如果使用純 CSS ，儘量依照不同用途來分開成不同的 CSS 檔案；
如果是 SASS 之類的模板語言，那則是用資料夾分出不同用途，然後用 include 合併。

前者的架構可能是：

	styles
	├─main.css       // 主要樣式
	├─login-form.css // 登入表單的樣式
	├─dialog.css     // 對話框樣式
	└─（下略）

後者的架構則可能是下面這樣

	styles
	├─main.css       // 主要樣式
	├─login-form     // 登入表單的樣式
	│  ├─_alert.scss
	│  ├─_input.scss
	|  └─_main.scss
	├─dialog         // 對話框樣式
	│  └─_dialog.scss
	└─（下略）

結語

其實應該是還有其他的啦，不過光是打這些就花掉好多時間了……

是說，我這份 Coding Style 和 Google 的根本是判若水火啊（苦笑

～雨雪紛飛(Blog)～

(ㅍ_ㅍ) 整理一下自己的 Coding Style