「回到我在贝尔实验室(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"