项目开发指引

关于项目的成本和收获

开发

文档

• 对于一个长期维护，多人合做，代码量巨大的项目须要花费时间写好并维护文档和注释 (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