# 文件撰寫 & 提高程式碼品質及有效提交 票卷實作分享
---
## 分享者：票卷組
1. 講者：Andrew
- 鹹魚,在共通BU組待了半年,後來調至票卷組至今
2. 協助者：Winni
- 前票卷組大佬,已經去其它地方高就,祝福她
---
# 論軟體工程師如何~~優雅的交接~~
---
## 起源
一切的一切都是為了~~跳槽~~的時候要留下完整的文件輔助交接
---
### 交接時存在的問題
---
### **Legacy Code**
---
1. 沒有文件
2. 文件沒有持續更新
3. 過去的開發人員皆已離職
4. 交接過於倉促
5. git提交紀錄不清不楚
---
---
## 該怎麼辦
* 邊看邊寫一份自己梳理過的文件
* 燒香拜佛放乖乖
* ~~看一個月後離職~~
* 最後時間抓緊交接的人問到飽
* 耐心的把每一行code看完
---
## 產品 > 一切事務
---
### 論交接時的心態
---
### 為何該開始寫文件？
---
---
---
# 寫文件之前的雜談
---
---
---
---
### 思考
「**可作用的軟體勝於完整的文件**」
working software over comprehensive documentation
---
### 文件的種類
- 整體規劃文件
- UML圖
- 產品需求與業務流程文件`
- 測試文件
- 環境架設文件
- 地雷總結的文件
---
### 文件是寫給誰看的?
1. 客戶
2. 自己
3. 團隊
4. 紀錄
---
### 撰寫文件的最佳時機
---
### 文件呈現的方式
* 自動產生文件派 - React Styleguidist
* 文件管理派 - docsify
* 手動撰寫文件派 - markdown README.md
---
### 自動產生文件派 - React Styleguidist
[線上範例](https://codesandbox.io/s/github/styleguidist/example/tree/master/?from-embed)
---
### 文件管理派 - docsify
[線上實例](https://cheng-hsiang.github.io/react-tutorial/#/)用法參考[官方](https://docsify.js.org/#/)
---
### 手動撰寫文件派 - markdown [票卷](https://hackmd.io/YH-e4sH9R9O3muyEQT-zvg)
[一看就會的教學](https://hackmd.io/features-tw?both#UML-%E5%9C%96%E8%A1%A8)
---
### 那其實以上這些都有一個共通的問題
---
---
## 關於程式碼品質的二三事
---
---
## DX(develop experience)
**開發體驗**
---
---
---
- 兩頁功能有87%像用了複製貼上(至少有五支以上這樣處理)
- 莫名其妙的命名-qqArray
- 註解寫的很糟糕
- 沒有持續更新的文件orz
- jQuery模組有些硬傷
- 祖傳規定:不可自動排版orz...
- 過度巢狀的三原運算子 `a>b?(c>d?(e>a?c=1:c=0):a=c):null`
---
---
---
---
[對ESLint有興趣自己看](https://wcc723.github.io/javascript/2018/01/01/javascript-eslint/)
---
<!-- 但最後移除了ESLint
 -->
---
## 那其實我覺得最好用的方法是
---
---
最後還是推一本聖經
[Clean Code](https://www.tenlong.com.tw/products/9789862017050)
---
# 優雅的提交
---
---
## 最重要的三個類型
* type
* scope
* subject
---
## 有很好的兩個類型
* body
* footer
---
# 關於type
- feat: 新增/修改功能 (feature)。
- fix: 修補 bug (bug fix)。
- docs: 文件 (documentation)。
- style: 格式 (不影響程式碼運行的變動 white-space, formatting, missing semi colons, etc)。
- refactor: 重構 (既不是新增功能，也不是修補 bug 的程式碼變動)。
- perf: 改善效能 (A code change that improves performance)。
- test: 增加測試 (when adding missing tests)。
- chore: 建構程序或輔助工具的變動 (maintain)。
- revert: 撤銷回覆先前的 commit 例如：revert: type(scope): subject (回覆版本：xxxx)。
---
```
Header: <type>(<scope>): <subject>
- type: 代表 commit 的類別：feat, fix, docs, style, refactor, test, chore，必要欄位。
- scope 代表 commit 影響的範圍，例如資料庫、控制層、模板層等等，視專案不同而不同，為可選欄位。
- subject 代表此 commit 的簡短描述，不要超過 50 個字元，結尾不要加句號，為必要欄位。
Body: 72-character wrapped. This should answer:
* Body 部份是對本次 Commit 的詳細描述，可以分成多行，每一行不要超過 72 個字元。
* 說明程式碼變動的項目與原因，還有與先前行為的對比。
Footer:
- 填寫任務編號（如果有的話）.
- BREAKING CHANGE（可忽略），記錄不兼容的變動，
以 BREAKING CHANGE: 開頭，後面是對變動的描述、以及變動原因和遷移方法。
```
---
### 讓大家commit message 規範與格式化
## [Commitizen](https://github.com/commitizen/cz-cli)
---
---
## 總結
---
參考文獻
https://kknews.cc/zh-tw/career/q4l2qjg.html
https://codertw.com/%E7%A8%8B%E5%BC%8F%E8%AA%9E%E8%A8%80/636814/
http://it.tomtang.idv.tw/2013/08/blog-post.html
http://it.tomtang.idv.tw/2013/03/blog-post.html
https://www.itread01.com/content/1548207551.html
https://ruddyblog.wordpress.com/tag/%E6%95%8F%E6%8D%B7%E9%96%8B%E7%99%BC%E9%9C%80%E8%A6%81%E5%93%AA%E4%BA%9B%E6%96%87%E4%BB%B6/
https://goiabada.blog/the-5-stages-of-dealing-with-legacy-code-6d578205beeb
https://blog.niclin.tw/2020/02/29/readable-code-1/?fbclid=IwAR0bSrQ-V0fhgdg8UnYlcmkKxxOF4PaICt0e4b2UootghisZdclPzY-rOlM
https://medium.com/@vincekuoyu/%E6%96%87%E6%80%9D%E4%B8%8D%E8%97%8F%E7%A7%81-%E5%8D%83%E8%90%AC%E4%B8%8D%E8%A6%81-%E7%B5%90%E9%9A%8A%E7%B7%A8%E7%A8%8B-58d3b6dd7857
https://medium.com/@benyihsia/attitude-to-deal-with-legacy-code-4687a38a00de
https://quickbirdstudios.com/blog/code-review-best-practices-guidelines/
https://ithelp.ithome.com.tw/users/20103676/ironman/1855
https://wadehuanglearning.blogspot.com/2019/05/commit-commit-commit-why-what-commit.html?m=1
---
Sign in with Wallet
Connect another wallet