昨天在开发 FixIt 的时候，在 Scss 中写 max(foo, bar) 函数比较不同的单位变量时报错了，但是在 CSS 中使用 max 或者 min 函数函数比较不同的单位变量是没有问题的。

造成这一问题的原因是，在 Scss 中，也实现了 max 和 min 函数，但是在 Scss 中，不同单位的变量是不能进行运算的，所以使得在 Scss 中直接使用 max 或者 min 函数会提示单位不同的报错。（同类 Less 中的变量运算是支持不同单位的）

知道造成问题的原因后，解决这个问题就很简单了，有很多种方法，有些方法感觉像在卡 BUG，有点意思，记录一下。

奇思淫技

1. 由于 Scss 区分大小写而 CSS 不区分，所以为了不让 Scss 中的函数覆盖 CSS 的函数，我们可以使用除了 max 以外的 2³ - 1 种写法，这样就能使用原生 CSS 的 max 函数来比较了，就不会报错了。

   1 2 3

   .foo { padding-left: MAX(10vh, 3.5rem); }

2. 使用 Scss 没有的 CSS 函数 clamp:

   clamp(MIN, VAL, MAX) 其实就是表示 max(MIN, min(VAL, MAX))

   1 2 3

   .foo { padding-left: clamp($header-height, 10vh, 10vh); }

3. 使用 unquote($string) 函数让 Scss 删除字符串最前和最后的单引号或双引号

   1 2 3

   .foo { padding-left: unquote('max(10vh, #{$header-height})'); }

By the way

如果需要在 CSS 函数内部恢复 Scss 解析（引用 Scss 变量），只需用 #{...} 包围 Scss 代码。

1
2
3
4
5

$header-height: 3.5rem !default;

.foo {
  margin: calc(10vh - $header-height);
}

上面的 Scss 将解析成 以下无效的 CSS 代码：

1
2
3

.foo {
  margin: calc(10vh - $header-height);
}

用 #{...} 包围 Scss 变量

1
2
3
4
5

$header-height: 3.5rem !default;

.foo {
  margin: calc(10vh - #{$header-height});
}

Sass 和 Less 都屬於 CSS 前置處理器，CSS 前置處理器定義了一種新的語言，其基本思想是，用一種專門的程式設計語言，為 CSS 增加了一些程式設計的特性，將 CSS 作為目標生成檔，然後開發者就只要使用這種語言進行 CSS 的編碼工作。
轉化成通俗易懂的話來說就是 “用一種專門的程式設計語言，進行 Web 頁面樣式設計，再通過編譯器轉化為正常的 CSS 檔，以供專案使用”。

為什麼，什麼時候要使用 CSS 前置處理器？ (Why, When)

CSS 有具體以下幾個缺點：

• 語法不夠強大，比如無法嵌套書寫，導致模組化開發中需要書寫很多重複的選擇器
• 沒有變數和合理的樣式複用機制，使得邏輯上相關的屬性值必須以字面量的形式重複輸出，導致難以維護

這就導致了我們在工作中無端增加了許多工作量。而使用 CSS 前置處理器可大大提高了我們的開發效率：

• 提供 CSS 缺失的樣式層複用機制
• 減少冗餘碼
• 提高樣式代碼的可維護性。

但是，CSS 的好處在於簡便、隨時隨地被使用和調試。這就使得預編譯 CSS 步驟的加入具有以下缺點：

• 開發工作流中多了一個環節，調試也變得更麻煩
• 預編譯很容易造成後代選擇器的濫用

所以我們在實際項目中衡量預編譯方案時，還是得想想，比起帶來的額外維護開銷，CSS 前置處理器有沒有解決更大的麻煩。

• 系統級框架開發 （大型複雜的樣式設計）
• 持續維護

Less、Sass/Scss 是什麼？ (What)

Less

是一種動態樣式語言。對 CSS 賦予了動態語言的特性，如變數、繼承、運算、函數。
Less 既可以在用戶端上運行 （支援 IE 6+, Webkit, Firefox)，也可在服務端運行。

Sass

是一種動態樣式語言，Sass 語法屬於縮排語法，
比 CSS 比多出好些功能（如變數、嵌套、運算，混入 (Mixin)、繼承、顏色處理，函數等），更容易閱讀。

Sass 與 Scss 的關係

Sass 的縮排語法，對於寫慣 CSS 的前端開發者來說很不直觀，也不能將 CSS 代碼加入到 Sass 裡面，因此 Sass 語法進行了改良，Sass 3 就變成了 Scss(Sassy CSS)。與原來的語法相容，只是用{}取代了原來的縮進。Sass 相當於 Scss 的嚴格模式。

Sass 和 Less 的比較

相同點

Less 和 Sass 在語法上有些共性，比如下面這些：

1. 混入 (Mixins)——class 中的 class
2. 參數混入——可以傳遞參數的 class，就像函數一樣
3. 嵌套規則——Class 中嵌套 class，從而減少重複的代碼
4. 運算——CSS 中用上數學
5. 顏色功能——可以編輯顏色
6. 名字空間 (namespace)——分組樣式，從而可以被調用
7. 作用域——局部修改樣式
8. JavaScript 賦值——在 CSS 中使用 JavaScript 運算式賦值

不同點

1. 實現方式

• Less 是基於 JavaScript，是在用戶端處理的
• Sass 是基於 Ruby 的，是在伺服器端處理的

2. 關於變數在 Less 和 Sass 中的唯一區別就是 Less 用@，Sass 用$
3. less 中的變量運算可帶、可不帶單位，Sass 需要帶單位元
4. 語法不同，請詳見 Less、Sass 官網

選用 Less 還是 Sass ?

無論是學習資料，討論情況，以及項目使用情況 Sass/Scss 都優於 Less，比如 Bootstrap 4 就使用的 Sass, 但是 Less 的使用更加簡單，使用門檻也較低，內網開發的情況，Less 則更加適合。

• 绝不写死代码，硬编码
• 不留不要用的、垃圾代码

Git

• Master 的 BUG 必须最少且趋近于零，为最稳定的版本
• 每次 Commit 信息应该准确填写。不可模棱两可，eg: 修复 BUG、增加功能
• 禁止 Commit IDE 的 project data，e.g: .vscode
• 禁止上传垃圾代码

更多规则详见文档 Commit 规范

分支（Branch）

• 命名规则：应以此分支主要目的命名（修复什么 BUG，新增特定功能）
• 合并后的分支应该删除

commit

• 遵循一个功能一个 commit 的原则

Restful

• 资源名词站在 API 的角度思考

  • 复数名词：可以复数笔数据，回传结果为 Array

    举例：GET/users 取得多笔使用者资料

    • 刪除，放在复数名词內，让 Router 保持一致性
    • 增加，放在复数名詞內，让 Router 保持一致性

  • 单数名词：仅取得单笔数据，必须指定 PK，两两一组，回传结果为 Object 举例：GET/user/{accont} 取得单笔使用者资料，必须指定 PK

• URL 中一律不带 id 参数

1
2

正确范例： calendar_manager/calendar/29
错误范例： calendar_manager/calendar/29?id=29

更多规则详见文档 RESTful

命名

• 命名应根据内容做有意义的命名，让后续维护人员可以顾名思义！
• 即使不会发生错误，代码英文大小写也需明确区分。

语意

字母与分隔

通用

• 代码编写
• 每个函数应该使用块注释，注释应包含函数功能说明、参数说明。规则见：JSDoc、JavaDoc
• 不必要的代码不要写，也应禁止放到注释里面！
• if-else 的 {} 严禁省略
• 代码规范、代码排版等可通过 eslint 等工具做统一处理

正确写法

1
2
3
4
5
6

public function test () {
  // do something
  if (a === b) {
    // do something
  }
}

错误写法

1
2
3
4
5
6
7
8

public function test ()
{
  // do something
  if (a === b)
  {
    // do something
  }
}

• 代码排版
  • 任何代码应该以 2 个 space 为一个缩进做好排版、不可使用 tab
• 函数 (Function, Methd)
  • 函数声明时需在函数上方加上函数注释，注释应包含函数说明、参数内容（参数类型、参数英文名称、参数说明）、返回值内容（返回值类型、返回值说明）
• 类 (Class)
  • 一个类（Class）的声明只能存在一个文件
  • 类（Class）的声明文件，文件名必须为类名
• 其他
  • 连接本地任何其他资源（图片、文件、网站）皆使用相对路径，禁止使用绝对路径，非本地资源除外

HTML

代码编写

• 禁止在 HTML 使用 <style>、<script>，一律使用外部档案引用方式引用 CSS、JavaScript 文件
• HTML 标签需成双成对，有头有尾
• 块级标签：<tag></tag>
• 单标签：<tag />
• 禁止使用已被 HTML 舍弃的旧标签、属性，如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<!-- html tag -->
<center>
<font>
<basefont>
<s>
<strike>
<u>
<listing>
<plaintext>
<xmp>
<!-- html attribute -->
align
bgcolor
color

CSS

CSS 的定义应该独立一个 CSS 文件，禁止使用 <style> 或 style 属性直接在 HTML 中定义样式。

JavaScript

禁止使用 HTML 字串，一律使用 Dom 产生 HTML, e.g: document.createDocumentFragment()

注释

JavaScript 注释应该遵循 JSDoc 的标准撰写

全局变量 (Global)

1

/* global ZT */

常量 (Constant)

1
2
3
4

/**
 * 常量說明
 * @type {常量类型}
 */

Example

1
2
3
4
5

/**
 * 请求地址
 * @type {String}
 */
const REQUEST_URL = 'http://localhost:8080';

函數、方法 (Function, Method)

1
2
3
4
5
6
7

/**
 * 函数用途说明
 * @param {参数类型} 参数名称参数说明
 * @param {参数类型} [选择性参数名称] 参数说明
 * @param {参数类型} [选择性参数名称=参数预设值] 参数说明
 * @returns {返回值类型} 返回值说明
 */

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

/**
 * 取得使用者
 * @param {Int} userId 使用者 ID
 * @param {Object} [options] 其他选项
 * @param {String} [options.query='a'] 查询关键词 默认为 'a'
 * @returns {Object} 使用者资料
 */
function getUser(userId, options) {
  // do something
  return user;
}

Vue

• 待补充

Java

Java 注释应该遵循 JavaDoc 的标准撰写

• 待补充

PHP

前端参数取得

参数取得需通过 filter_input 函数取得，不得使用 _GET 、_POST

输出到前台

参数命名必须为：全部小写，不同单字以「_」分隔

注解

PHP 注解应该遵循 PHPDoc 的标准撰写

成员变量 (Member)

成员变量只的是 Class 内的成员变数，我们都会要求替成员变量增加注解说明。通常 Function 的变量除非太特别否则都不需要特别注解说明。

1
2
3
4

/**
 * 成员变量說明
 * @type {类型}
 */

Example

1
2
3
4
5

/**
 * 使用者 ID
 * @type {String}
 */
$userId = 'Hello';

函数、方法 (Function, Method)

1
2
3
4
5
6
7

/**
 * 函数用途说明
 * @param 参数型态 参数名称 参数说明
 * @option 参数选项类型 参数选项名称 参数选项说明
 * @uses 全局变量 全域变数说明
 * @returns 返回值类型 返回值说明
 */

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

/**
 * 取得使用者
 * @param int userId 使用者 ID
 * @param object options 其他选项
 * @option string options['query'] 查询关键字
 * @uses $_POST['role_id'] 从前端以 POST 取得角色 ID
 * @returns object 使用者资料
 */
function getUser ($userId, $options) {
  // do something
  return $user;
};

Python

• 待补充

Database

• 禁止使用 Table Join。
• 禁止使用 Oracle Trigger。
• 禁止将查询数据库的 SQL 放在循环中查询

SQL 撰写

• 属于 SQL 语法使用大写（SELECT，WHERE，INSERT etc..）
• 属于使用者自己定义的使用小写（表名 table name，字段名 column name etc..）
• 表名、字段名前后需加上 `

Example

1

INSERT INTO `user` VALUES('a', 'b');

统一用词

系统中常用词，例如弹出框按钮、搜索框等，仅为举例，不限与此。