如果團隊有提交的範本需要遵守，以團隊的共識為優先。但無論是不是有提交原則，重點就是把標題跟內容寫清楚，讓 Review 的工程師能夠有效率把提交者的程式碼做檢視。以下就是自己的經驗分享跟自己在提交程式碼的時候會注意的事情：

標題

若有單號加單號。有 User Story 或需求的就擺在這邊，或是有什麼要提醒 Reviewer 也可擺在這邊。以下舉一些例子來說明示意：

⭕ 好的，能夠一眼看得出來這個提交內容是什麼。讓 Reviewer 可以安心點看看是什麼，而不是因為標題殺人。

• #12345 嫁接人物列表 model 和 API
• 嫁接人物列表 model 和 API
• 優化呼叫 API 顯示 Loading 效果
• 修正 API < 23 status bar 的 icon 白色問題

✖️不清楚的：不知道提交的內容，而且標題也會讓人疑惑滿滿為什麼有這些異動們。

• 嫁接 API

  提交的是什麼 API？功能是什麼？這是什麼需求？

• Bug fix

  修正什麼問題？修正了什麼？改了什麼？

• 重構 xxxActivity

  為什麼重構這個？異動的範圍有多少？會影響的範圍有多少？

敘述

很多的 Pull Request 的服務，在敘述上都可以使用 markdown 的語法。擅用語法可以讓敘述的易讀性提高，先來看看一個例子：

可以使用假資料進行測試
[規格需求]請見 User Story : https://hyperlink
[畫面對照]請見 zeplin: https://zeplin.xxx
[操作路徑]首頁 > 下方 Tab A > 點擊藍色按鈕

在 github 上呈現會這樣如下：

另一個試了一下 AWS Code Commit ，提交後內容會像是截圖如下：

Pull Request 的服務都會有預覽的內容，就像 iT鐵人賽也是使用 markdown 也有預覽的功能。所以看到這樣的排版，通常會詢問提交者有沒有檢查過敘述。

在看到上述的例子之後，可以藉由 markdown 改善排版呢？首先，如果有需要 highlight 的標題，可以調整字級。如果有連結的話，把要顯示連結的文字用 [] 包起來，接著放 () 要導入的連結過去。最後是項目分級，可以使用 - 或是數字來一一顯示，這邊是採用「-」來做改善

### 可以使用假資料進行測試
- 規格需求，請見 [User Story](https://hyperlink)
- 畫面對照，請見 [zeplink](https://zeplin.xxx)
- 操作路徑：首頁 > 下方 Tab A > 點擊藍色按鈕

實際上看到的畫面會是：

改善了排版，但是其中的有些不清楚的地方，像是假資料是什麼？也許是團隊共用的名詞那就 ok。有些時候在看程式碼的時候，也許是多個人在同個專案進行，有可能遇到對方不是很了解這個名詞。所以這邊再改一下，讓 Reviewer 可以了解。

- 可使用 **list.json** 測資進行 Unit Test 跟程式碼邏輯驗證
- 規格需求，請見 [User Story](https://hyperlink)
- 畫面對照，請見 [zeplink](https://zeplin.xxx)
- 操作路徑：首頁 > 下方 Tab A > 點擊藍色按鈕

改成指定的某個測資才能驗證程式碼，比原本模糊的大方向的文字上來說清楚許多。

大家在提交程式碼的時候會注意什麼呢？

參考資料

• Google Engineering Practices Documentation
• 10 tips for reviewing code you don’t like
• Code Readability of LINE Android Team