iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 19
0
自我挑戰組

30 天開發 Android App 的流水帳系列 第 19

Day 19:如何寫一個好的 Pull Request 敘述

如果團隊有提交的範本需要遵守,以團隊的共識為優先。但無論是不是有提交原則,重點就是把標題跟內容寫清楚,讓 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 上呈現會這樣如下:
https://ithelp.ithome.com.tw/upload/images/20201009/20130546uz9clDYlpv.png

另一個試了一下 AWS Code Commit ,提交後內容會像是截圖如下:
https://ithelp.ithome.com.tw/upload/images/20201009/201305460vt4TMrAXI.png

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

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

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

實際上看到的畫面會是:

https://ithelp.ithome.com.tw/upload/images/20201009/20130546Bgla4ZJ2P4.png

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

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

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

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

參考資料


上一篇
Day 18:如何當個 Code Reviewer
下一篇
Day 20:重構的好時機
系列文
30 天開發 Android App 的流水帳32

尚未有邦友留言

立即登入留言