「回到我在貝爾實驗室(The Bell Lab)工作的日子。我們有個不嚴謹的發現，採用一致性的縮排風格是降低程式錯誤率的最顯著指標之一。」

「我們原本希望架構或程式語言或其他更高概念的東西是影響品質的因素，當我們以為專業能力歸功於對工具的掌握和高尚的設計方法時，那些寫程式的人(Coder)，僅僅是在應用程式裡添加一致的縮排風格就產生了價值」」

取自: Clean Code (p.xii)

就從最簡單的變數命名、註解，及編排來介紹吧~ 希望每一位不論初學者或是老手，在看完本日文章後都能回頭去審視自己有沒有注意過這些很簡單的細節呢? 這之前，筆者先行補充各大語言的編程風格與慣例，讓有興趣的讀者們可自行去了解。這邊須先提醒，關於程式碼的風格 (Style) 或慣例 (Conventions)，在不同語言上的實踐都有差異

Coding Conventions & Style Guide

C#

C# 來說可以參考微軟官方文件: C# Coding Conventions

Python

Python 的話官方文件則有 PEP 8 -- Style Guide
可以看到其實與 C# 的 Codeing 風格有些不同，即使只是宣告基本的資料結構而已

JavaScript & TypeScript

JavaScript & TypeScript 的編碼風格又像是另一個世界了...

Ref: Google JavaScript Style Guide、Google TypeScript Style Guide

Doc Comments

如果對 註解風格 及 API 文件規格 的產生也很注重，也可參考：

• JSDoc
  • 微軟將 TFS 內的 JavaScript 改寫為 TypeScript 時，也是得益於統一的註解風格和程式慣例，使他們能依靠自動化工具大大加快轉換的效率
  • Ref: Typescript – a real world story of adoption in TFS
• Swagger
  • 是一個滿方便的 API 文件化 & 視覺化於瀏覽器的套件。筆者目前只在 .NET 用過而已
  • 想了解更多可參考看看國軍的 MND Open Api 簡單瀏覽一下後就能快速上手使用他們的開放 API 了

SQL

SQL 語法的可讀性是很多人常忽略的，簡單引用 2 個例子比對：

/* 查閱文章資料 */
select albums.title, albums.release_date, albums.recording_date, albums.production_date 
from albums where albums.title='Charcoal Lane'
or albums.title='The New Danger';


-- Which one is more clean!?


/* 查閱文章資料 */
SELECT a.title,
       a.release_date, a.recording_date, a.production_date
  FROM albums AS a
 WHERE a.title = 'Charcoal Lane'
    OR a.title = 'The New Danger';

Ref: SQL樣式指南 · SQL Style Guide

HTML

即使是最簡單的 HTML 也能從一致的編排風格中受益，可以從 w3schools 給出的範例中發現不同編排風格所帶來的差別: HTML Style Guide and Coding Conventions

Git Commit Message Conventions

在多人團隊的協作過程，版控工具也有其對應的 Conventions，如下圖:

Ref: Git – Commit Message Conventions、Git Commit Message 這樣寫會更好，替專案引入規範與範例

• 附上 2 個筆者以前的 Commit Messages 作為反面例子 (QQ...)
  
  看圖說故事可發現：
  • 間隔幾週後我已經想不出起每次改版在幹嘛了
  • 後來稍微寫了點 Commit Messages
  • 至今我們仍然可從當時的 Commit 中看出，當時是把某個顏色遊戲以 Component-Based 的方式重構

要是當時就知道 Git Commit Conventions，我就能更好的維護和整理作品了!

• 再附上一張學生時期熬夜趕 Final Project 造就的奇特 Commit:
  

相信如果不是因為大家都坐在附近，其他的成員根本沒辦法得知我每一次的改版都做了些什麼...。Commit Messages 風格很重要的應用就在於: 團隊協作時讓彼此能夠快速了解進度狀況!

小結

• 建議學習一門新語言或是工具之前或之後，都可以至少去快速瀏覽過各自對應的 Coding Conventions & Style Guide
• 必須再強調，編排風格沒有固定答案，重點在於團隊使用一致的風格，來增加可讀性、減少交接與後續維護成本
• 最後，可以再思考，有沒有可能讓上述提到的種種規範都由某類自動化工具檢查程式碼風格呢?
  這已超出本系列書籍範圍了，有興趣的讀者可以搜尋關鍵字: "Linter", "ESLint", "Git Hooks"