項目開發指引

關於項目的成本和收穫

開發

文檔

• 對於一個長期維護，多人合做，代碼量巨大的項目須要花費時間寫好並維護文檔和註釋 (must)

  • 選擇合適的 format, 好比 markdown, texinfo 等等，格式不要過於複雜，那會增長寫文檔的枯燥程度

  • 合適的機制保持代碼和文檔的同步

    比較常見的做法是根據所用語言的區塊爲單位添加註釋 (function, class, module 等等)，這即能保持代碼模塊的邊界清晰，也比較符合直覺 (rails 文檔屬於優秀範例，使用 rdoc 格式)

api

使用並保持一致的API規範，遵循 REST 和 jsonapi.org 能夠免去不少細節上的煩惱

• http://json-schema.org
• http://jsonapi.org
• http://swagger.io

命名 (self-documenting)

函數命名

依據其所包含代碼的邏輯的意義而命名，而不是依據業務的需求 (自底向上 instead 自頂向下)

舉個例子，韓國和中國在相同領域的市場行爲不一樣，有的開發者可能就使用 kr_func, cn_func 進行簡單的業務邏輯封裝，而這樣的代碼不是 self-documenting 的，這樣的代碼須要註釋完整

def kr_biz_name
  # Keroa biz
end

def cn_biz_name
  # China biz
end

更好的做法是使用單一命名做爲此業務接口

• 減小接口，減小維護成本
• 函數名爲代碼註釋

def biz_name(country)
  case country
  when :cn
    biz1_func
    biz2_func
  when :kr
    biz1_func
    biz3_func
  end
end

configurable

hardcode 每每帶來維護成本，而編寫可配置靈活地代碼每每須要更多的設計和編碼量，多數時候還須要編寫並維護文檔。因此預想一下這個需求的增加可能，而後決定。這也是 refactor 的時候最常遇到的問題

流程 (可控)

code review

• 保持單個 pull request 的規模，同義爲保持單個需求對代碼變動的規模，減少 review 負擔
  • 拆分需求
  • 儘可能不要在需求變動中摻入太多 refactor，使用獨立的 PR

continuous integration

不少文檔都講這個，再也不贅述

staging and release

• 固定並保持 staging 和 release 頻率，使用 feature freeze, milestone, release tag 讓事情有計劃，可預見

維護

refactor

對於一個成長中的項目，重構應該伴隨着項目目標的變動而產生，若是僅僅是代碼的微小優化多數時候便沒有必要，會增長額外的風險，併產生新的維護成本

運營

A/B testing (Experiment Driven Development)

• https://github.com/splitrb/split
• https://github.com/assaf/vanity

參考

• http://playbook.thoughtbot.com
• http://12factor.net
• data migration
  • [使用臨時腳本更新數據，使用 migration 更新 schema] https://robots.thoughtbot.com/data-migrations-in-rails