改善代码质量编程规范 - 学习总结

命名与注释

命名

范围

• 项目名
• 包名
• 接口名
• 类名
• 函数名
• 变量名
• 参数名

原则建议

• 准确达意
  • 对不同作用域，合理选择不同的长度。作用域较小如局部变量，可使用较短的缩写。
  • 参考经典开源系统，使用耳熟能详的名字
• 借助上下文简化命名
  • 借助类的信息简化属性和函数的命名，无需在属性和函数名字中再加入类名
  • 借助函数的信息简化参数的命名
• 增加可读、可搜索醒
  • 避免使用生僻，不好读的英文单词
  • 要符合项目的统一规范，不要使用反直觉的命名
• 与当前项目统一接口命名方式，不要独树一帜

注释

注释应该写什么

• 做什么 - What
• 为什么 - Why
• 怎么做 - How

原则建议

• 注释比代码承载的信息更多
• 注释可以起到总结性文档的作用
• 总结性注释可以帮助让代码结构更加清晰
• 注释并非越多越好
  • 建议类和函数适当添加尽可能详细、全面的注释
  • 函数内部注释减少，通过好的命名