项目开发指引

2019独角兽企业重金招聘Python工程师标准>>>

关于项目的成本和收获

开发

文档

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

转载于:https://my.oschina.net/xieyunzi/blog/508597