# 注釋以及格式化

## 注釋
:::info
大部分時候,注釋都是不好的
(如果使用好的命名法,代碼就可以大幅減少解釋的需求)
不需要過多注釋就能看懂
這種情況下注釋就是冗余的
因為你並不需要
增加注釋只是增加你閱讀代碼的時間(注釋不能跳過,因為**可能**包含重要資訊),但不會增加你對代碼的理解
:::

### 壞注釋
- 包含冗余的資訊
- 分區/區塊注釋
- 代碼應通過 class 和分割檔案來分割功能,如果需要分區/區塊注釋,那很可能是代碼沒有適當切分在檔案中(全部塞到一個檔案)
- 我在讀 Enzyme 時常看到(可能是為了優化 gas 所做,但這並不是很優雅)
- 有誤導性的注釋
- 注釋掉的代碼
- 用途：
- 藏掉代碼
- 留著做為參考
- 有新版本的
- 有用途,但是不應該永久留存
- 如果有需要回頭查看,應該使用git

### 好注釋
- 規定(法定)注釋
- 作者
- 授權
- 創建時間
- 不能被好的命名方式所取代的,代碼解釋
- ex.
- regex
- 警告你不能做某些事
- ex.
- 此 API 只能使用於 js 瀏覽器環境
- TODO Note
- 對於未完成的代碼
- 但也不能太多
- Doc String

## 格式化
代碼格式化增加代碼的可讀性和意義傳遞正確性
- 垂直格式化
- 格式所有代碼架構,從檔案的開始到結束
- 內容：
- 行間距
- 代碼分區
- 橫向格式化
- 格式化單行代碼
- 內容：
- 縮進
- 空白間隔
- 代碼寬度

### 正確的格式化
- 重要且會增加代碼可讀性
- 在各語言間都不同
- 遵守代碼風格

### 垂直格式化
- 應該要能像作文一樣被閱讀
- 由上而下,沒有太多**跳躍**
- 把檔案切分為多個小觀念(ex. class),並且放進多個檔案
- ex.
- 一個檔案有多個 class
- 不同概念要使用區塊來區分(區塊間有空行)
- 讓閱讀順暢,盡量減少跳躍
- 方法/函數排序
- 上面用到的方法,在下面宣告 -> 閱讀流暢
- 要看語言：JS 可以, Python 不行(函式一定要先定義)

### 水平格式化
代碼應該在不用左右移動下可讀,避免過長的句子
- 如果太長的話
- 使用縮進
- 使用變數(賦值部分代碼)
- 使用清楚且可讀的命名
##
###### tags: `Clean Code` `Note`