---
# System prepended metadata

title: 注釋以及格式化
tags: [Note, Clean Code]

---

# 注釋以及格式化

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



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

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

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

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

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

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